Ffigen
FFI binding generator
Install / Use
/learn @dart-archive/FfigenREADME
This package has moved!
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
Cheaders, 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
Example
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)>();
}
}
Using this package
- Add
ffigenunderdev_dependenciesin yourpubspec.yaml(rundart pub add -d ffigen). - Add
package:ffiunderdependenciesin yourpubspec.yaml(rundart pub add ffi). - Install LLVM (see Installing LLVM).
- Configurations must be provided in
pubspec.yamlor in a custom YAML file (see configurations). - Run the tool-
dart run ffigen.
Jump to FAQ.
Installing LLVM
package:ffigen uses LLVM. Install LLVM (9+) in the following way.
Linux
-
Install libclangdev.
With apt-get:
sudo apt-get install libclang-dev.With dnf:
sudo dnf install clang-devel.
Windows
- Install Visual Studio with C++ development support.
- Install LLVM or
winget install -e --id LLVM.LLVM.
MacOS
- Install Xcode.
- Install Xcode command line tools -
xcode-select --install. - Install LLVM -
brew install llvm.
Configurations
Configurations can be provided in 2 ways-
- In the project's
pubspec.yamlfile 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-
<table> <thead> <tr> <th>Key</th> <th>Explaination</th> <th>Example</th> </tr> <colgroup> <col> <col style="width: 100px;"> </colgroup> </thead> <tbody> <tr> <td>output<br><i><b>(Required)</b></i></td> <td>Output path of the generated bindings.</td> <td>output: 'generated_bindings.dart'
or
output:
bindings: 'generated_bindings.dart'
...
llvm-path:
- '/usr/local/opt/llvm'
- 'C:\Program Files\llvm`
- '/usr/lib/llvm-11'
# Specify exact path to dylib
- '/usr/lib64/libclang.so'
headers:
entry-points:
- 'folder/**.h'
- 'folder/specific_header.h'
include-directives:
- '**index.h'
- '**/clang-c/**'
- '/full/path/to/a/header.h'
name: 'SQLite'
description: 'Bindings to SQLite'
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: false
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:
exclude:
# Typedefs starting with `p` are not generated.
- 'p.*'
rename:
# Removes '_' from beginning of a typedef.
'_(.*)': '$1'
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:
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:
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:
# Matches with the generated name.
'NoPackStruct': none # No packing
'.*': 1 # Pack all structs with value 1
