dart-use-ffigen

Guides agents to generate Dart FFI bindings with package:ffigen (the FfiGenerator API) instead of writing them by hand. Hand-written bindings are described as error-prone and brittle, so whenever native headers exist or are produced by a build step, manual DynamicLibrary.lookup calls, @Native external functions, and raw struct classes should be avoided in favor of generated code. The skill establishes conventions for where generator scripts, headers, and outputs live, and how to filter what gets generated.

The workflow places the generator script at tool/ffigen.dart within the target package, resolving paths relative to Platform.script so it runs from any working directory. Third-party headers belong in third_party/ (or a src/ directory at the package root), and generated bindings that reference third-party headers must go under lib/src/third_party/ with the primary file using a .g.dart extension. Dependencies are added with dart pub add dev:ffigen, the script is run via dart run tool/ffigen.dart, and the result is verified with dart analyze. The generator runs the Dart formatter automatically when format is set to true.

Configuration is programmatic through objects imported from package:ffigen/ffigen.dart. FfiGenerator orchestrates parsing and generation and accepts Headers, Enums, Functions, Globals, Integers, Macros, Structs, Typedefs, Unions, UnnamedEnums, an optional ObjectiveC, and a required Output. Headers configures entryPoints, an include filter for transitive headers, compilerOptions, and ignoreSourceErrors. Functions selects exposed symbols via include or Functions.includeSet, with isLeaf and recordUse options. Output sets dartFile, recordUseMapping, preamble, and format. Important constraints include using targeted inclusion filters rather than importing an entire library, supplying a preamble with the matching license, the native copyright header, and an auto-generation warning, and enabling recordUse plus a recordUseMapping .g.dart file when bindings participate in native asset tree shaking. Style lints in generated files are suppressed via ignore_for_file in the preamble; genuine compilation errors should be reported upstream rather than edited manually.