The package can now be found at https://github.com/dart-lang/native/tree/main/pkgs/ffigen
Binding generator for FFI bindings.
Note: ffigen only supports parsing
C
headers, notC++
headers.
This bindings generator can be used to call C code -- or code in another language that compiles to C modules that follow the C calling convention -- such as Go or Rust. For more details, see: https://dart.dev/guides/libraries/c-interop
ffigen also has experimental support for calling ObjC and Swift code; for details see: https://dart.dev/guides/libraries/objective-c-interop
For some header file example.h:
int sum(int a, int b);
Add configurations to Pubspec File:
ffigen:
output: 'generated_bindings.dart'
headers:
entry-points:
- 'example.h'
Output (generated_bindings.dart).
import 'dart:ffi' as ffi;
class NativeLibrary {
final ffi.Pointer<T> Function<T extends ffi.NativeType>(String symbolName)
_lookup;
NativeLibrary(ffi.DynamicLibrary dynamicLibrary)
: _lookup = dynamicLibrary.lookup;
NativeLibrary.fromLookup(
ffi.Pointer<T> Function<T extends ffi.NativeType>(String symbolName)
lookup)
: _lookup = lookup;
int sum(int a, int b) {
return _sum(a, b);
}
late final _sumPtr = _lookup<ffi.NativeFunction<ffi.Int Function(ffi.Int, ffi.Int)>>('sum');
late final _sum = _sumPtr.asFunction<int Function(int, int)>();
}
}
- Add
ffigen
underdev_dependencies
in yourpubspec.yaml
(rundart pub add -d ffigen
). - Add
package:ffi
underdependencies
in yourpubspec.yaml
(rundart pub add ffi
). - Install LLVM (see Installing LLVM).
- Configurations must be provided in
pubspec.yaml
or in a custom YAML file (see configurations). - Run the tool-
dart run ffigen
.
Jump to FAQ.
package:ffigen
uses LLVM. Install LLVM (9+) in the following way.
-
Install libclangdev.
With apt-get:
sudo apt-get install libclang-dev
.With dnf:
sudo dnf install clang-devel
.
- Install Visual Studio with C++ development support.
- Install LLVM or
winget install -e --id LLVM.LLVM
.
- Install Xcode.
- Install Xcode command line tools -
xcode-select --install
. - Install LLVM -
brew install llvm
.
Configurations can be provided in 2 ways-
- In the project's
pubspec.yaml
file under the keyffigen
. - Via a custom YAML file, then specify this file while running -
dart run ffigen --config config.yaml
The following configuration options are available-
Key | Explaination | Example |
---|---|---|
output (Required) |
Output path of the generated bindings. |
output: 'generated_bindings.dart' or output:
bindings: 'generated_bindings.dart'
... |
llvm-path | Path to llvm folder. ffigen will sequentially search for `lib/libclang.so` on linux, `lib/libclang.dylib` on macOs and `bin\libclang.dll` on windows, in the specified paths. Complete path to the dynamic library can also be supplied. Required if ffigen is unable to find this at default locations. |
llvm-path:
- '/usr/local/opt/llvm'
- 'C:\Program Files\llvm`
- '/usr/lib/llvm-11'
# Specify exact path to dylib
- '/usr/lib64/libclang.so' |
headers (Required) |
The header entry-points and include-directives. Glob syntax is allowed. If include-directives are not specified ffigen will generate everything directly/transitively under the entry-points. |
headers:
entry-points:
- 'folder/**.h'
- 'folder/specific_header.h'
include-directives:
- '**index.h'
- '**/clang-c/**'
- '/full/path/to/a/header.h' |
name (Prefer) |
Name of generated class. |
name: 'SQLite' |
description (Prefer) |
Dart Doc for generated class. |
description: 'Bindings to SQLite' |
compiler-opts | Pass compiler options to clang. You can also pass these via the command line tool. |
compiler-opts:
- '-I/usr/lib/llvm-9/include/' and/or via the command line - dart run ffigen --compiler-opts "-I/headers
-L 'path/to/folder name/file'" |
compiler-opts-automatic -> macos -> include-c-standard-library | Tries to automatically find and add C standard library path to
compiler-opts on macos. Default: true |
compiler-opts-automatic:
macos:
include-c-standard-library: false |
functions structs unions enums unnamed-enums macros globals |
Filters for declarations. Default: all are included. Options - - Include/Exclude declarations. - Rename declarations. - Rename enum and struct members. - Expose symbol-address for functions and globals. |
functions:
include: # 'exclude' is also available.
# Matches using regexp.
- [a-z][a-zA-Z0-9]*
# '.' matches any character.
- prefix.*
# Matches with exact name
- someFuncName
# Full names have higher priority.
- anotherName
rename:
# Regexp groups based replacement.
'clang_(.*)': '$1'
'clang_dispose': 'dispose'
# Removes '_' from beginning.
'_(.*)': '$1'
symbol-address:
# Used to expose symbol address.
include:
- myFunc
structs:
rename:
# Removes prefix underscores
# from all structures.
'_(.*)': '$1'
member-rename:
'.*': # Matches any struct.
# Removes prefix underscores
# from members.
'_(.*)': '$1'
enums:
rename:
# Regexp groups based replacement.
'CXType_(.*)': '$1'
member-rename:
'(.*)': # Matches any enum.
# Removes '_' from beginning
# enum member name.
'_(.*)': '$1'
# Full names have higher priority.
'CXTypeKind':
# $1 keeps only the 1st
# group i.e only '(.*)'.
'CXType(.*)': '$1'
globals:
exclude:
- aGlobal
rename:
# Removes '_' from
# beginning of a name.
'_(.*)': '$1' |
typedefs | Filters for referred typedefs. Options - - Include/Exclude (referred typedefs only). - Rename typedefs. Note: Typedefs that are not referred to anywhere will not be generated. |
typedefs:
exclude:
# Typedefs starting with `p` are not generated.
- 'p.*'
rename:
# Removes '_' from beginning of a typedef.
'_(.*)': '$1' |
functions -> expose-typedefs | Generate the typedefs to Native and Dart type of a function Default: Inline types are used and no typedefs to Native/Dart type are generated. |
functions:
expose-typedefs:
include:
# Match function name.
- 'myFunc'
# Do this to expose types for all function.
- '.*'
exclude:
# If you only use exclude, then everything
# not excluded is generated.
- 'dispose' |
functions -> leaf | Set isLeaf:true for functions. Default: all functions are excluded. |
functions:
leaf:
include:
# Match function name.
- 'myFunc'
# Do this to set isLeaf:true for all functions.
- '.*'
exclude:
# If you only use exclude, then everything
# not excluded is generated.
- 'dispose' |
functions -> variadic-arguments | Generate multiple functions with different variadic arguments. Default: var args for any function are ignored. |
functions:
variadic-arguments:
myfunc:
// Native C types are supported
- [int, unsigned char, long*, float**]
// Common C typedefs (stddef.h) are supported too
- [uint8_t, intptr_t, size_t, wchar_t*]
// Structs/Unions/Typedefs from generated code or a library import can be referred too.
- [MyStruct*, my_custom_lib.CustomUnion] |
structs -> pack | Override the @Packed(X) annotation for generated structs. Options - none, 1, 2, 4, 8, 16 You can use RegExp to match with the generated names. Note: Ffigen can only reliably identify packing specified using __attribute__((__packed__)). However, structs packed using `#pragma pack(...)` or any other way could potentially be incorrect in which case you can override the generated annotations. |
structs:
pack:
# Matches with the generated name.
'NoPackStruct': none # No packing
'.*': 1 # Pack all structs with value 1 |
comments | Extract documentation comments for declarations. The style and length of the comments recognized can be specified with the following options- style: doxygen(default) | any length: brief | full(default) If you want to disable all comments you can also pass comments: false. |
comments:
style: any
length: full |
structs -> dependency-only unions -> dependency-only |
If `opaque`, generates empty `Opaque` structs/unions if they
were not included in config (but were added since they are a dependency) and
only passed by reference(pointer). Options - full(default) | opaque |
structs:
dependency-only: opaque
unions:
dependency-only: opaque |
sort | Sort the bindings according to name. Default: false, i.e keep the order as in the source files. |
sort: true |
use-supported-typedefs | Should automatically map typedefs, E.g uint8_t => Uint8, int16_t => Int16, size_t => Size etc. Default: true |
use-supported-typedefs: true |
use-dart-handle | Should map `Dart_Handle` to `Handle`. Default: true |
use-dart-handle: true |
exclude-all-by-default |
When a declaration filter (eg `functions:` or `structs:`) is empty or
unset, it defaults to including everything. If this flag is enabled, the
default behavior is to exclude everything instead. Default: false |
exclude-all-by-default: true |
preamble | Raw header of the file, pasted as-it-is. |
preamble: |
// ignore_for_file: camel_case_types, non_constant_identifier_names |
library-imports | Specify library imports for use in type-map. Note: ffi (dart:ffi) is already available as a predefined import. |
library-imports:
custom_lib: 'package:some_pkg/some_file.dart' |
type-map | Map types like integers, typedefs, structs, unions to any other type. Sub-fields - typedefs, structs, unions, ints lib must be specified in library-imports or be one of a predefined import. |
type-map:
'native-types': # Targets native types.
'char':
'lib': 'pkg_ffi' # predefined import.
'c-type': 'Char'
# For native-types dart-type can be be int, double or float
# but same otherwise.
'dart-type': 'int'
'int':
'lib': 'custom_lib'
'c-type': 'CustomType4'
'dart-type': 'int'
'typedefs': # Targets typedefs.
'my_type1':
'lib': 'custom_lib'
'c-type': 'CustomType'
'dart-type': 'CustomType'
'structs': # Targets structs.
'my_type2':
'lib': 'custom_lib'
'c-type': 'CustomType2'
'dart-type': 'CustomType2'
'unions': # Targets unions.
'my_type3':
'lib': 'custom_lib'
'c-type': 'CustomType3'
'dart-type': 'CustomType3' |
ffi-native |
WARNING: Native support is EXPERIMENTAL. The API may change
in a breaking way without notice.
Generate `@Native` bindings instead of bindings using `DynamicLibrary` or `lookup`. |
ffi-native:
assetId: 'myasset' # Optional. |
language |
WARNING: Other language support is EXPERIMENTAL. The API may change
in a breaking way without notice.
Choose the input langauge. Must be one of 'c', or 'objc'. Defaults to 'c'. |
language: 'objc' |
output -> symbol-file | Generates a symbol file yaml containing all types defined in the generated output. |
output:
...
symbol-file:
# Although file paths are supported here, prefer Package Uri's here
# so that other pacakges can use them.
output: 'package:some_pkg/symbols.yaml'
import-path: 'package:some_pkg/base.dart' |
import -> symbol-files | Import symbols from a symbol file. Used for sharing type definitions from other pacakges. |
import:
symbol-files:
# Both package Uri and file paths are supported here.
- 'package:some_pkg/symbols.yaml'
- 'path/to/some/symbol_file.yaml' |
Key | Explaination | Example |
---|---|---|
objc-interfaces | Filters for interface declarations. This option works the same as other declaration filters like `functions` and `structs`. |
objc-interfaces:
include:
# Includes a specific interface.
- 'MyInterface'
# Includes all interfaces starting with "NS".
- 'NS.*'
exclude:
# Override the above NS.* inclusion, to exclude NSURL.
- 'NSURL'
rename:
# Removes '_' prefix from interface names.
'_(.*)': '$1' |
objc-interfaces -> module | Adds a module prefix to the class name when loading the class from the dylib. This is only relevent for ObjC headers that are generated wrappers for a Swift library. See example/swift for more information. |
headers:
entry-points:
# Generated by swiftc to wrap foo_lib.swift.
- 'foo_lib-Swift.h'
objc-interfaces:
include:
# Eg, foo_lib contains a set of classes prefixed with FL.
- 'FL.*'
module:
# Use 'foo_lib' as the module name for all the FL.* classes.
# We don't match .* here because other classes like NSString
# shouldn't be given a module prefix.
'FL.*': 'foo_lib' |
cd examples/<example_u_want_to_run>
, Rundart pub get
.- Run
dart run ffigen
.
See test/README.md
Ffigen supports regexp based renaming, the regexp must be a
full match, for renaming you can use regexp groups ($1
means group 1).
E.g - For renaming clang_dispose_string
to string_dispose
.
We can can match it using clang_(.*)_(.*)
and rename with $2_$1
.
Here's an example of how to remove prefix underscores from any struct and its members.
structs:
...
rename:
'_(.*)': '$1' # Removes prefix underscores from all structures.
member-rename:
'.*': # Matches any struct.
'_(.*)': '$1' # Removes prefix underscores from members.
The default behaviour is to include everything directly/transitively under
each of the entry-points
specified.
If you only want to have declarations directly particular header you can do so
using include-directives
. You can use glob matching to match header paths.
headers:
entry-points:
- 'path/to/my_header.h'
include-directives:
- '**my_header.h' # This glob pattern matches the header path.
Ffigen supports including/excluding declarations using full regexp matching.
Here's an example to filter functions using names
functions:
include:
- 'clang.*' # Include all functions starting with clang.
exclude:
- '.*dispose': # Exclude all functions ending with dispose.
This will include clang_help
. But will exclude clang_dispose
.
Note: exclude overrides include.
Ffigen treats char*
just as any other pointer,(Pointer<Int8>
).
To convert these to/from String
, you can use package:ffi. Use ptr.cast<Utf8>().toDartString()
to convert char*
to dart string
and "str".toNativeUtf8()
to convert string
to char*
.
Unnamed enums are handled separately, under the key unnamed-enums
, and are generated as top level constants.
Here's an example that shows how to include/exclude/rename unnamed enums
unnamed-enums:
include:
- 'CX_.*'
exclude:
- '.*Flag'
rename:
'CXType_(.*)': '$1'
This happens when an excluded struct/union is a dependency to some included declaration. (A dependency means a struct is being passed/returned by a function or is member of another struct in some way)
Note: If you supply structs
-> dependency-only
as opaque
ffigen will generate
these struct dependencies as Opaque
if they were only passed by reference(pointer).
structs:
dependency-only: opaque
unions:
dependency-only: opaque
By default the native pointers are private, but you can use the
symbol-address
subkey for functions/globals and make them public by matching with its name. The pointers are then accesible via nativeLibrary.addresses
.
Example -
functions:
symbol-address:
include:
- 'myFunc' # Match function name.
- '.*' # Do this to expose all function pointers.
exclude: # If you only use exclude, then everything not excluded is generated.
- 'dispose'
By default these types are inline. But you can use the expose-typedef
subkey
for functions to generate them. This will expose the Native and Dart type.
E.g - for a function named hello
, the generated typedefs are named
as NativeHello
and DartHello
.
Example -
functions:
expose-typedefs:
include:
- 'myFunc' # Match function name.
- '.*' # Do this to expose types for all function.
exclude: # If you only use exclude, then everything not excluded is generated.
- 'dispose'
Named declarations use their own names even when inside another typedef. However, unnamed declarations inside typedefs take the name of the first typedef that refers to them.
The following typedefs are not generated -
- They are not referred to anywhere in the included declarations.
- They refer to a struct/union having the same name as itself.
- They refer to a boolean, enum, inline array, Handle or any unsupported type.
ffigen
uses clang
's own compiler frontend to parse and traverse the C
header files. ffigen
expands the macros using clang
's macro expansion and then traverses the expanded code. To do this, ffigen
generates temporary files in a system tmp directory.
A custom temporary directory can be specified by setting the TEST_TMPDIR
environment variable.
Ffigen can sometimes generate a lot of logs, especially when it's parsing a lot of code.
SEVERE
logs are something you definitely need to address. They can be caused due to syntax errors, or more generally missing header files (which need to be specified usingcompiler-opts
in config)WARNING
logs are something you can ignore, but should probably look into. These are mostly indications of declarations ffigen couldn't generate due to limitations of dart:ffi, private declarations (which can be resolved by renaming them via ffigen config) or other minor issues in the config file itself.- Everything else can be safely ignored. It's purpose is to simply let you know what ffigen is doing.
- The verbosity of the logs can be changed by adding a flag with
the log level. E.g -
dart run ffigen --verbose <level>
. Level options are -[all, fine, info (default), warning, severe]
. Theall
andfine
will print a ton of logs are meant for debugging purposes only.
Ffigen can share type definitions using symbol files.
- A package can generate a symbol file using the
output -> symbol-file
config. - And another package can then import this, using
import -> symbol-files
config. - Doing so will reuse all the types such as Struct/Unions, and will automatically exclude generating other types (E.g functions, enums, macros).
Checkout examples/shared_bindings
for details.
For manually reusing definitions from another package, the library-imports
and type-map
config can be used.