[experiment] Part 2 of refactor c-interop guides to support hooks. #12839

antfitch · 2025-12-18T07:21:53Z

Description of what this PR is changing or adding, and why:

Refactor the layout of the c-interop guides to make it clear what hooks support and what they don't.

Required reviewer: @dcharkes

gemini-code-assist · 2025-12-18T07:22:16Z

Summary of Changes

Hello @antfitch, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly refactors the C-interop documentation for Android, iOS, and macOS. The primary goal is to provide clearer guidance on integrating native code by distinguishing between the newer 'build hooks' approach and the 'legacy FFI plugin' method. The changes aim to help developers choose the appropriate method based on their needs and provide detailed instructions for each, improving the overall clarity and usability of the documentation.

Highlights

Clarified C-Interop Approaches: The guides now clearly differentiate between using dart:ffi with 'build hooks' and the 'legacy FFI plugin' approach for native code integration across Android, iOS, and macOS.
Introduced Build Hooks Guidance: New sections detail how to access native code using @Native annotations with build hooks, emphasizing their benefits such as OS-agnostic build scripts and uniform native code access.
Reorganized Content for Clarity: Existing sections on creating FFI packages, platform libraries, and third-party support have been restructured and renamed to explicitly distinguish between build hook and legacy FFI plugin contexts.
Updated Guide Titles and Descriptions: The titles and descriptions of the Android, iOS, and macOS c-interop guides have been updated to reflect the inclusion of build hooks as a primary integration method.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request refactors the C-interop guides for Android, iOS, and macOS to better distinguish between the modern 'build hooks' approach and the 'legacy FFI plugin' approach. The changes significantly improve the structure and clarity of the documentation. I've found a few minor issues, such as typos and some content that could be better placed, and one more significant issue in the macOS guide where important sections have been accidentally commented out. Overall, this is a great improvement to the documentation.

gemini-code-assist · 2025-12-18T07:24:00Z

src/content/platform-integration/android/c-interop.md

+
+## Overview
+
+Flutter mobile and desktop apps can use [build hooks][] or the the [dart:ffi][]


There's a small typo here.

Suggested change

Flutter mobile and desktop apps can use [build hooks][] or the the [dart:ffi][]

Flutter mobile and desktop apps can use [build hooks][] or the [dart:ffi][]

gemini-code-assist · 2025-12-18T07:24:00Z

src/content/platform-integration/android/c-interop.md


+:::note
+If you are using the legacy `plugin_ffi`,
 You should also add attributes to indicate that the


Minor grammatical correction: 'You' should be lowercase as it's not the start of a new sentence.

Suggested change

You should also add attributes to indicate that the

you should also add attributes to indicate that the

I left the same comment, not seeing that the bot had already done so. Though, to be honest, I'd just delete the "You should also" entirely. :)

gemini-code-assist · 2025-12-18T07:24:00Z

src/content/platform-integration/ios/c-interop.md

+
+## Overview
+
+Flutter mobile and desktop apps can use [build hooks][] or the the [dart:ffi][]


There's a small typo here.

Suggested change

Flutter mobile and desktop apps can use [build hooks][] or the the [dart:ffi][]

Flutter mobile and desktop apps can use [build hooks][] or the [dart:ffi][]

gemini-code-assist · 2025-12-18T07:24:01Z

src/content/platform-integration/ios/c-interop.md

 Before your library or program can use the FFI library
 to bind to native code, you must ensure that the
 native code is loaded and its symbols are visible to Dart.
 This page focuses on compiling, packaging,
 and loading iOS native code within a Flutter plugin or app.


This paragraph contains general information about FFI that applies to both build hooks and legacy plugins. It might be clearer to move it out of the 'Accessing native code (build hooks)' section and place it at a higher level, for example, directly under the 'Overview' section.

gemini-code-assist · 2025-12-18T07:24:01Z

src/content/platform-integration/ios/c-interop.md


+:::note
+If you are using the legacy `plugin_ffi`,
 You should also add attributes to indicate that the


Minor grammatical correction: 'You' should be lowercase as it's not the start of a new sentence.

Suggested change

You should also add attributes to indicate that the

you should also add attributes to indicate that the

gemini-code-assist · 2025-12-18T07:24:01Z

src/content/platform-integration/macos/c-interop.md

+
+## Overview
+
+Flutter mobile and desktop apps can use [build hooks][] or the the [dart:ffi][]


There's a small typo here.

Suggested change

Flutter mobile and desktop apps can use [build hooks][] or the the [dart:ffi][]

Flutter mobile and desktop apps can use [build hooks][] or the [dart:ffi][]

gemini-code-assist · 2025-12-18T07:24:01Z

src/content/platform-integration/macos/c-interop.md

 Before your library or program can use the FFI library
 to bind to native code, you must ensure that the
 native code is loaded and its symbols are visible to Dart.
 This page focuses on compiling, packaging,
 and loading macOS native code within a Flutter plugin or app.


This paragraph contains general information about FFI that applies to both build hooks and legacy plugins. It might be clearer to move it out of the 'Accessing native code (build hooks)' section and place it at a higher level, for example, directly under the 'Overview' section.

gemini-code-assist · 2025-12-18T07:24:01Z

src/content/platform-integration/macos/c-interop.md


+:::note
+If you are using the legacy `plugin_ffi`,
 You should also add attributes to indicate that the


Minor grammatical correction: 'You' should be lowercase as it's not the start of a new sentence.

Suggested change

You should also add attributes to indicate that the

you should also add attributes to indicate that the

flutter-website-bot · 2025-12-18T07:29:34Z

Visit the preview URL for this PR (updated for commit 0927c58):

https://flutter-docs-prod--pr12839-hooks-update-2-h8cqy3rp.web.app

dcharkes

This is still super messy.

I think the pages should flow as follows:

general intro explaining the two major approaches: build hooks&code assets and legacy FFI plugins
Everything related to build hooks - should have 0 references to legacy FFI plugins
Everything related to legacy FFI plugins - should have 1 references to code hooks.

Currently it is all mixed and matched, which makes it very confusing for users. It causes a lot of cognitive overload.

dcharkes · 2025-12-18T07:40:23Z

src/content/platform-integration/android/c-interop.md

-[Binding to native iOS code using dart:ffi][ios-ffi].
-For information in macOS, see
-[Binding to native macOS code using dart:ffi][macos-ffi].
 This feature is not yet supported for web plugins.


This note belongs to legacy FFI plugins. Ditto on the other pages.

dcharkes · 2025-12-18T07:40:34Z

src/content/platform-integration/android/c-interop.md

+
+Flutter mobile and desktop apps can use [build hooks][] or the the [dart:ffi][]
+library to call native C APIs. FFI stands for
+[_foreign function interface._][FFI]. Other terms for similar functionality


double period

dcharkes · 2025-12-18T07:48:04Z

src/content/platform-integration/android/c-interop.md

+
+## Overview
+
+Flutter mobile and desktop apps can use [build hooks][] or the the [dart:ffi][]


build hooks also use dart:ffi, maybe it's better to

Flutter mobile and desktop apps can use the
[dart:ffi][] library to call native C APIs.
FFI stands for [foreign function interface.][FFI]
Other terms for similar functionality include
native interface and language bindings.
The FFI can be used in two ways:

via code assets reported in build hooks, in which Flutter takes care of bundling the native code, and

via legacy FFI plugins where you have to write the build files yourself.

(new bullet points)

Prefer using build hooks.

dcharkes · 2025-12-18T07:50:35Z

src/content/platform-integration/android/c-interop.md

 so in C++ these symbols are marked `extern "C"`.

+:::note
+If you are using the legacy `plugin_ffi`,


This makes no sense under the header for build hooks. This note should be under the header legacy FFI plugins.

dcharkes · 2025-12-18T07:52:06Z

src/content/platform-integration/ios/c-interop.md

 [dart:ffi]: {{site.dart.api}}/dart-ffi/dart-ffi-library.html
 [FFI]: https://en.wikipedia.org/wiki/Foreign_function_interface

+### Accessing native code (build hooks)


Maybe this section makes more sense as a subsection under "create an FFI package"

dcharkes · 2025-12-18T07:52:30Z

src/content/platform-integration/ios/c-interop.md

+your Dart code won't need to change.

-## Dynamic vs static linking
+### Dynamic vs static linking (legacy FFI plugin)


And this section makes more sense under the FFI plugin section

sfshaza2

Yeah, I'd like to see tabs used in this page: one for legacy, another for build hooks, and whatever else makes sense if you need more.

I'm going to go ahead and approve, but consider making that change.

sfshaza2 · 2025-12-18T13:42:47Z

src/content/platform-integration/android/c-interop.md


+:::note
+If you are using the legacy `plugin_ffi`,
 You should also add attributes to indicate that the


I left the same comment, not seeing that the bot had already done so. Though, to be honest, I'd just delete the "You should also" entirely. :)

sfshaza2 · 2025-12-18T13:45:25Z

src/content/platform-integration/android/c-interop.md

+### Open-source third-party support
+
+For open source, build the C/C++ sources in your build hook. Or build the
+sources on GitHub actions and download the binary from github artifacts on


github=>GitHub

Though I am not sure what "GitHub artifacts" are. Does it just mean things that are built by/on GitHub?

sfshaza2 · 2025-12-18T13:46:19Z

src/content/platform-integration/android/c-interop.md

-## Other use cases
-
-### Platform library
+### Platform library (legacy FFI plugin)


Do we need this parenthetical in a header?

I understand that this page shows the new (hooks) vs the old (legacy). But what I think would be much cleaner would be to use tabs in the page rather than a potentially confusing set of "legacy" headers. A tab for build hooks and a tab for legacy.

antfitch · 2025-12-18T16:03:23Z

@sfshaza2, these older docs are very heavy. @dcharkes and I had a chat. The new plan is to create a new, smaller topic for hooks and to mark these older topics as obsolete (we don't delete them because they may still be useful).

Refactor c-interop docs to support hooks.

0927c58

antfitch requested a review from dcharkes December 18, 2025 07:21

antfitch requested review from a team and sfshaza2 as code owners December 18, 2025 07:21

antfitch marked this pull request as draft December 18, 2025 07:22

gemini-code-assist bot reviewed Dec 18, 2025

View reviewed changes

dcharkes reviewed Dec 18, 2025

View reviewed changes

sfshaza2 approved these changes Dec 18, 2025

View reviewed changes

antfitch closed this Dec 18, 2025

antfitch deleted the hooks_update_2 branch December 18, 2025 16:03

antfitch changed the title ~~Part 2 of refactor c-interop guides to support hooks.~~ [experiment] Part 2 of refactor c-interop guides to support hooks. Dec 18, 2025


		## Overview

		Flutter mobile and desktop apps can use [build hooks][] or the the [dart:ffi][]

	You should also add attributes to indicate that the
	you should also add attributes to indicate that the

[experiment] Part 2 of refactor c-interop guides to support hooks. #12839

[experiment] Part 2 of refactor c-interop guides to support hooks. #12839

Uh oh!

Conversation

antfitch commented Dec 18, 2025

Uh oh!

gemini-code-assist bot commented Dec 18, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

flutter-website-bot commented Dec 18, 2025

Uh oh!

dcharkes left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sfshaza2 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

antfitch commented Dec 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants