dart-use-ffigen

Name: dart-use-ffigen
Author: flutter

787installs159forks

How to install dart-use-ffigen?

flutter/agent-plugins/dart-use-ffigen

$npx -y skills add flutter/agent-plugins --skill dart-use-ffigen

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	# Generating FFI Bindings using package:ffigen
2
3	## Contents
4	- [Introduction](#introduction)
5	- [Constraints](#constraints)
6	- [FFIgen Overview](#ffigen-overview)
7	- [Step-by-Step Workflow](#step-by-step-workflow)
8	- [Concrete Example: Binding a C Library](#concrete-example-binding-a-c-library)
9	- [Verification Checklist](#verification-checklist)
10
11	## Introduction
12
13	Automate and standardize the generation of FFI bindings using `package:ffigen` (`FfiGenerator`). Writing FFI bindings by hand is error-prone, brittle, and highly discouraged.
14
15	## Constraints
16
17	* 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.
18	* Generator Location: The generator script should be located at `tool/ffigen.dart` within the target package root.
19	* 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/`).
20	* 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).
21	* 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`).
22	* 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.`).
23	* 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`.
24	* Record Usage and Tree Shaking: If the package is integrated into standard runtime execution or compiles native assets via native hooks:
25	* Enable recorded usage on all functions by setting `recordUse: (_) => true` under `Functions`.
26	* 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.
27
28	## FFIgen Overview
29
30	To construct the programmatic generator, use the core configuration objects imported from `package:ffigen/ffigen.dart`:
31
32	### 1. `FfiGenerator`
33	The parent class that orchestrates the configuration, parsing, and code generation.
34	```dart
35	FfiGenerator({
36	Headers headers = const Headers(),
37	Enums enums = Enums.excludeAll,
38	Functions functions = Functions.excludeAll,
39	Globals globals = Globals.excludeAll,
40	Integers integers = const Integers(),
41	Macros macros = Macros.excludeAll,
42	Structs structs = Structs.excludeAll,
43	Typedefs typedefs = Typedefs.excludeAll,
44	Unions unions = Unions.excludeAll,
45	UnnamedEnums unnamedEnums = UnnamedEnums.excludeAll,
46	ObjectiveC? objectiveC,
47	required Output output,
48	}).generate();
49	```
50
51	### 2. `Headers`
52	Configures Clang header parsing targets and compiler flags.
53	* `entryPoints`: A list of target header `Uri` inputs.
54	* `include`: A filter function `bool Function(Uri header)` that handles transitive header imports.
55	* `compilerOptions`: Custom preprocessor/include compiler flags to pass directly to libclang.
56	* `ignoreSourceErrors`: Set to `true` to silence errors occurring inside third-party headers during parsing.
57
58	### 3. `Functions`
59	Specifies which native C/C++ functions to expose in Dart.
60	* `include`: A matcher function (e.g. `(decl) => {'my_func'}.contains(decl.originalName)` or `Functions.includeSet({'my_func'})`).
61	* `isLeaf`: Declares functions as leaf functions (`(decl) => true`) if they do not call back into Dart or block thread execution.
62	* `recordUse`: Enables metadata generation for native asset tree shaking

People who liked this also viewed

6 picks

Type

dart-use-ffigen

787installs159forks

View on GitHub

How to install dart-use-ffigen?

flutter/agent-plugins/dart-use-ffigen

$npx -y skills add flutter/agent-plugins --skill dart-use-ffigen

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Generating FFI Bindings using package:ffigen
2
3	## Contents
4	- [Introduction](#introduction)
5	- [Constraints](#constraints)
6	- [FFIgen Overview](#ffigen-overview)
7	- [Step-by-Step Workflow](#step-by-step-workflow)
8	- [Concrete Example: Binding a C Library](#concrete-example-binding-a-c-library)
9	- [Verification Checklist](#verification-checklist)
10
11	## Introduction
12
13	Automate and standardize the generation of FFI bindings using `package:ffigen` (`FfiGenerator`). Writing FFI bindings by hand is error-prone, brittle, and highly discouraged.
14
15	## Constraints
16
17	* 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.
18	* Generator Location: The generator script should be located at `tool/ffigen.dart` within the target package root.
19	* 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/`).
20	* 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).
21	* 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`).
22	* 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.`).
23	* 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`.
24	* Record Usage and Tree Shaking: If the package is integrated into standard runtime execution or compiles native assets via native hooks:
25	* Enable recorded usage on all functions by setting `recordUse: (_) => true` under `Functions`.
26	* 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.
27
28	## FFIgen Overview
29
30	To construct the programmatic generator, use the core configuration objects imported from `package:ffigen/ffigen.dart`:
31
32	### 1. `FfiGenerator`
33	The parent class that orchestrates the configuration, parsing, and code generation.
34	```dart
35	FfiGenerator({
36	Headers headers = const Headers(),
37	Enums enums = Enums.excludeAll,
38	Functions functions = Functions.excludeAll,
39	Globals globals = Globals.excludeAll,
40	Integers integers = const Integers(),
41	Macros macros = Macros.excludeAll,
42	Structs structs = Structs.excludeAll,
43	Typedefs typedefs = Typedefs.excludeAll,
44	Unions unions = Unions.excludeAll,
45	UnnamedEnums unnamedEnums = UnnamedEnums.excludeAll,
46	ObjectiveC? objectiveC,
47	required Output output,
48	}).generate();
49	```
50
51	### 2. `Headers`
52	Configures Clang header parsing targets and compiler flags.
53	* `entryPoints`: A list of target header `Uri` inputs.
54	* `include`: A filter function `bool Function(Uri header)` that handles transitive header imports.
55	* `compilerOptions`: Custom preprocessor/include compiler flags to pass directly to libclang.
56	* `ignoreSourceErrors`: Set to `true` to silence errors occurring inside third-party headers during parsing.
57
58	### 3. `Functions`
59	Specifies which native C/C++ functions to expose in Dart.
60	* `include`: A matcher function (e.g. `(decl) => {'my_func'}.contains(decl.originalName)` or `Functions.includeSet({'my_func'})`).
61	* `isLeaf`: Declares functions as leaf functions (`(decl) => true`) if they do not call back into Dart or block thread execution.
62	* `recordUse`: Enables metadata generation for native asset tree shaking

People who liked this also viewed

6 picks

Type