Guide agents to use `package:ffigen` to automatically generate FFI bindings instead of writing them manually. Use this skill when a task involves writing new FFI bindings, extending C/Objective-C/Swift integrations, or replacing hand-crafted `dart:ffi` setups.

Generating FFI Bindings using package:ffigen Contents [Introduction]( introduction) [Constraints]( constraints) [FFIgen Overview]( ffigen overview) [Step by Step Workflow]( step by step workflow) [Concrete Example: Binding a C Library]( concrete example binding a c library) [Verification Checklist]( verification checklist) Introduction Automate and standardize the generation of FFI bindings using package:ffigen ( FfiGenerator ). Writing FFI bindings by hand is error prone, brittle, and highly discouraged. Constraints No Hand Written FFI Bindings : If native headers ( .h files) exist or are generated by a build step, never write manual DynamicLibrary.lookup , @Native external functions, or raw struct classes. Always use FfiGenerator to generate them. Generator Location : The generator script should be located at tool/ffigen.dart within the target package root. Header Location : If the native header files are third party, they should be located in third party/ within the target package (otherwise placing them in a src/ directory at the package root is also acceptable). If the headers are not in one of these standard locations, notify the user that it would be cleaner to move the header files to the standard location (e.g., third party/ ). Targeted Inclusion Filters : Avoid importing an entire native library unless specifically needed. Always apply precise inclusion lists using positive matches to minimize the size and cognitive load of the generated code (e.g., using Functions.includeSet or filtering matches in include closures). Output Setup : If the generated FFI bindings interface with a third party library (or reference third party headers), the generated files must always be placed under lib/src/third party/ . The primary generated FFI bindings file must strictly use the .g.dart extension (e.g. sqlite3.g.dart ). Preamble & License Headers : Always supply a premium preamble in the Output class to specify the license. This must match the native third party library's license, explicitly include the copyright header of the target native header file, and contain an automatic generation warning (e.g. // Generated by package:ffigen. Do not edit manually. ). No Unnecessary Commits of Stale Bindings : Ensure you run the generator script and check if the generated files have changed before finishing your task. Always verify the package by running dart analyze . Record Usage and Tree Shaking : If the package is integrated into standard runtime execution or compiles native assets via native hooks: Enable recorded usage on all functions by setting recordUse: ( ) = true under Functions . Specify the recordUseMapping target in Output (which must strictly be a .g.dart file under lib/src/third party/ , e.g. lib/src/third party/sqlite3.record use mapping.g.dart ) to register bindings for symbol tree shaking. FFIgen Overview To construct the programmatic generator, use the core configuration objects imported from package:ffigen/ffigen.dart : 1. FfiGenerator The parent class that orchestrates the configuration, parsing, and code generation. 2. Headers Configures Clang header parsing targets and compiler flags. entryPoints : A list of target header Uri inputs. include : A filter function bool Function(Uri header) that handles transitive header imports. compilerOptions : Custom preprocessor/include compiler flags to pass directly to libclang. ignoreSourceErrors : Set to true to silence errors occurring inside third party headers during parsing. 3. Functions Specifies which native C/C++ functions to expose in Dart. include : A matcher function (e.g. (decl) = {'my func'}.contains(decl.originalName) or Functions.includeSet({'my func'}) ). isLeaf : Declares functions as leaf functions ( (decl) = true ) if they do not call back into Dart or block thread execution. recordUse : Enables metadata generation for native asset tree shaking (essential in dart lang/native ). Set to ( ) = true . 4. Output Configures target generated files. dartFile : Target Uri where the primary FFI bindings will be written. recordUseMapping : Target Uri for recorded usage metadata maps (crucial for linking time tree shaking). preamble : Text inserted at the top of the generated file (licensing, annotations). format : Set to true to run the Dart formatter automatically. Step by Step Workflow Step 1: Check/Add Dependencies Open the package's pubspec.yaml and verify the dev dependencies contains ffigen . Use the Dart MCP server or look up the latest version on [pub.dev](https://pub.dev/packages/ffigen) (e.g., ^20.1.1 ). You can add it automatically using the CLI: Step 2: Formulate Paths Dynamically Create a programmatic generator script under the package's tool/ directory (e.g., tool/ffigen.dart ). Resolve paths relative to Platform.script to make sure it runs successfully from any working directory: Step 3: Write the Script ( tool/ffigen.dart ) Define void main() and run FfiGenerator with dynamic options (see complete example below). Step 4: Run Code Generation Execute the script from the terminal inside the target package folder: Step 5: Static Analysis Verify that the generated bindings are correct and resolve any analysis issues. FFIgen automatically runs the Dart formatter on the output file (via format: true configuration), so manual formatting is not required. 1. Run the static analyzer inside the target package: 2. Addressing Warnings/Lints : If dart analyze reports style or lint warnings inside the generated file, append the corresponding warning codes to the ignore for file: list in your generator script's preamble configuration (e.g., adding camel case types , non constant identifier names , etc.). Do not modify the package's global rules. 3. Addressing Compilation Errors : If dart analyze reports actual compiler or analysis errors (not warnings) inside the generated file, do not attempt to edit the generated file manually. Report these error details directly to the user so they can file an issue on the repository at [github.com/dart lang/native](https://github.com/dart lang/native). Concrete Example: Binding a C Library Let's assume we are working with the SQLite package under pkgs/code assets/example/sqlite , which embeds SQLite C library sources inside third party/sqlite/ and accesses it via FFI. The C Header File ( third party/sqlite/sqlite3.h ) BEFORE: Manual FFI Binding (The Anti Pattern) A developer might attempt to handcraft this integration. It is fragile, blocks tree shaking metadata, and is highly prone to ABI and structural mapping issues: AFTER: Generating via FFIgen (The Correct Pattern) Create a programmatic script at tool/ffigen.dart : Running the Generator script Run this in the package root directory: This will automatically create: 1. lib/src/third party/sqlite3.g.dart 2. lib/src/third party/sqlite3.record use mapping.g.dart Verification Checklist Always perform the following verification before completing a binding generation task: 1. Correct Setup : Verify the target generated files are inside lib/src/third party/ (required for third party licensed code) and the primary FFI bindings file strictly uses the .g.dart extension. 2. Static Analysis : Run dart analyze and ensure there are zero compiler/analyzer errors or warnings in the package. If static warnings are reported in the generated bindings, suppress them by adding ignore for file rules to the generator's preamble configuration (do not modify global package rules). If actual compiler or analyzer errors are reported in the generated bindings, do not edit the generated file manually. Report the details to the user and direct them to file an issue at [github.com/dart lang/native](https://github.com/dart lang/native).

dart-use-ffigen