[hooks] Document flutter create --template=package_ffi

[dcharkes]

The Flutter docs were still recommending plugin_ffi for interop instead of package_ffi.

This leads to LLMs generating Plugin FFI code instead of build hooks. @antfitch believes making our documentation up to date should lead to LLMs generating the right thing.

The situation is not as clear-cut as simply deleting the old docs, as there are still valid use cases for using FFI plugins such as accessing the Flutter plugin API. However, it should be clear that the new recommended way for bundling dynamic libraries or accessing system libraries via build hooks and @Native() external functions.

cc @stuartmorgan-g How do you feel about marking the old FFI plugins as deprecated in the docs in accordance with flutter/flutter#131209? Flutter Plugins (non-FFI) are not deprecated. It's the use cases using dart:ffi and FFIgen that should use the new path mostly.

FYI @jwill You might also be looking into docs.

cc @mariamhas This is intended to address the EAP feedback.

[gemini-code-assist]

Summary of Changes

Hello @dcharkes, 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 updates the Flutter documentation regarding Foreign Function Interface (FFI) usage. It establishes package_ffi as the preferred template for binding to native code, leveraging build hooks for a streamlined development experience. While promoting this new approach, it also clearly delineates the scenarios where the older plugin_ffi template remains a valid, albeit legacy, option, ensuring users can make informed decisions based on their specific needs.

Highlights

• Documentation Update for FFI: The documentation has been updated to promote flutter create --template=package_ffi as the recommended method for FFI interop since Flutter 3.38.
• Legacy FFI Plugin Clarification: Existing plugin_ffi documentation is now explicitly marked as "legacy" but includes clear use cases where it remains relevant, such as accessing the Flutter Plugin API or specific platform configurations.
• New Comprehensive FFI Guide: A new documentation page (src/content/platform-integration/c-interop.md) has been added, providing a detailed guide on creating and using package_ffi templates, including explanations of build hooks and generated bindings.
• Navigation Menu Integration: The new FFI documentation page has been integrated into the site's navigation menu for easy access.

🧠 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.

Footnotes

1. 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 does a great job of updating the FFI documentation to recommend the new package_ffi template. The new documentation page is clear and comprehensive, and the legacy pages are correctly marked with warnings explaining the valid use cases for the old approach. I've added a couple of minor suggestions to improve consistency in the documentation.

[flutter-website-bot]

Visit the preview URL for this PR (updated for commit 202d0ea):

https://flutter-docs-prod--pr12845-build-hooks-docs-o35es4kr.web.app

[sfshaza2]

Some nits about a list. Otherwise lgtm

[stuartmorgan-g]

The situation is not as clear-cut as simply deleting the old docs, as there are still valid use cases for using FFI plugins such as accessing the Flutter plugin API.

That's not an FFI plugin though, that's an actual plugin that happens to use FFI as a communication mechanism. It shouldn't require any special template that I'm aware of.

cc @stuartmorgan-g How do you feel about marking the old FFI plugins as deprecated in the docs in accordance with flutter/flutter#131209?

Yes, we should definitely update the docs as part of deprecating the template.

(To clarify, by "as part of" I just mean as part of the overall process; I don't see any reason we can't switch docs to recommending hooks immediately, even though template deprecation will take a while to reach stable.)

[antfitch]

Small change to make sure we don't have all of these c-interop.md files in then TOC anymore.

[dcharkes]

The situation is not as clear-cut as simply deleting the old docs, as there are still valid use cases for using FFI plugins such as accessing the Flutter plugin API.

That's not an FFI plugin though, that's an actual plugin that happens to use FFI as a communication mechanism. It shouldn't require any special template that I'm aware of.

Right, we should point to the normal plugin documentation then.

However, if users end up adding C/C++ code to their plugins to use via dart:ffi, the documentation in the old pages on how to not get your code tree-shaken by the native compiler. Let's discuss in the next sync.

[dcharkes]

@antfitch The preview website doesn't want to load https://flutter-docs-prod--pr12845-build-hooks-docs-o35es4kr.web.app/platform-integration/c-interop ? It forwards to https://flutter-docs-prod--pr12845-build-hooks-docs-o35es4kr.web.app/platform-integration/ .

[antfitch]

Thanks for updating the TOC. I've also updated the filename for the new topic to be 'bind-native-code.md' since it seems more accurate and should not present issues with redirects.