dart-use-ffigen

Generating FFI Bindings using package:ffigen

Contents

• Introduction
• Constraints
• FFIgen Overview
• Step-by-Step Workflow
• Concrete Example: Binding a C Library
• 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.