In Flutter, what does flutter create --template=package_ffi set up, and how do its build hook and ffigen config deliver a C library to the app?

## The problem the template solves Shipping a C library in a Flutter app used to mean writing a build file per platform: Gradle and CMake for Android, a `.podspec` for iOS and macOS, `CMakeLists.txt` for Linux and Windows, plus Dart code that opened the right file on each OS. **Build hooks** (formerly *native assets*, stable in Dart 3.10) move that into one Dart script run by the SDK, and the Flutter documentation recommends the `package_ffi` template built on them since Flutter 3.38. ## What the template creates `flutter create --template=package_ffi imgz` produces: | File | Role | |---|---| | `src/imgz.c`, `src/imgz.h` | the C sources and header | | `hook/build.dart` | the **build hook**, run by the SDK to compile the C code | | `ffigen.yaml` | configuration for `package:ffigen` | | `lib/imgz_bindings_generated.dart` | generated `@Native` external functions | | `lib/imgz.dart` | the package's public Dart API wrapping the bindings | | `test/imgz_test.dart` | a unit test calling the native function | | `pubspec.yaml` | depends on `hooks`, `code_assets`, `native_toolchain_c`; `ffigen` and `ffi` as dev dependencies | ## The build hook ```dart import 'package:hooks/hooks.dart'; import 'package:logging/logging.dart'; import 'package:native_toolchain_c/native_toolchain_c.dart'; void main(List<String> args) async { await build(args, (input, output) async { final String packageName = input.packageName; final CBuilder cbuilder = CBuilder.library( name: packageName, assetName: '${packageName}_bindings_generated.dart', sources: ['src/$packageName.c'], ); await cbuilder.run(input: input, output: output, logger: Logger('')); }); } ``` - The SDK invokes the hook for each target OS and architecture it builds. - `CBuilder.library` compiles the sources with the platform's toolchain and adds a **code asset** to the output. - The **asset name** is the bindings library, so its id becomes `package:imgz/imgz_bindings_generated.dart`, exactly the default `assetId` of the `@Native` functions declared in that file. That is how the functions find their library without any loading code. - The same mechanism can **link a system library** (`LookupInProcess()`, or `DynamicLoadingSystem(...)` for a Windows DLL) or bundle a **prebuilt binary** downloaded and hash-verified in the hook (`DynamicLoadingBundled()`). ## The bindings ```bash dart run ffigen --config ffigen.yaml ``` `ffigen.yaml` names the header entry points, the output file, and sets `ffi-native:` so the generator emits `@Native` externals instead of a class wrapping a `DynamicLibrary`. Regenerate whenever the header changes, and review the diff: it is the contract between Dart and C. ## The public API layer The template's `lib/imgz.dart` shows the intended layering: - A short function is re-exported as a plain synchronous call. - A long-running function is wrapped in an asynchronous API that sends the work to a helper isolate, because a long native call on the main isolate blocks Dart execution and drops frames. ## When the legacy template still applies The Flutter tool prints that `plugin_ffi` is deprecated in favour of `package_ffi`. The documentation keeps it for three cases: code that needs the **Flutter plugin API**, **static linking** on iOS and macOS, and configuring a **Google Play services runtime** on Android. ## Pitfalls - Hook output names must be identical across architectures and across iOS device and simulator SDKs, or the tool cannot combine them into a universal binary or an XCFramework. - An app using `calloc` or `Arena` in its own code needs `package:ffi` as a regular dependency; the template only lists it for development.