ffigen 20.0.0-dev.1

ffigen: ^20.0.0-dev.1 copied to clipboard

Introduction #

Bindings generator for FFI bindings.

Note: FFIgen only supports parsing C headers, not C++ 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.cn/guides/libraries/c-interop.

FFIgen also has experimental support for calling ObjC and Swift code; for details see https://dart.cn/guides/libraries/objective-c-interop.

Getting Started #

This guide demonstrates how to call a custom C API from a standalone Dart application. It assumes that Dart has been set up (instructions) and that LLVM is installed on the system (instructions). Furthermore, it assumes that the Dart app has been created via dart create ffigen_example.

1. Add the utility package package:ffi as a dependency and the bindings generator package:ffigen as a dev_dependency to the pubspec of your app by running: dart pub add ffi dev:ffigen.

2. Write the C code and place it inside a subdirectory of your app. For this example we will place the following code in src/add.h and src/add.c respectively. It defines a simple API to add two integers in C.

   // in src/add.h:
      
   int add(int a, int b);
   

   // in src/add.c:
      
   int add(int a, int b) {
     return a + b;
   }
   

3. To generate the bindings, we will write a script using package:ffigen and place it under tool/ffigen.dart. The script instantiates and configures a FfiGenerator. Refer to the code comments below and the API docs to learn more about available configuration options.

   import 'dart:io';
   
   import 'package:ffigen/ffigen.dart';
      
   void main() {
     final packageRoot = Platform.script.resolve('../');
     FfiGenerator(
       // Required. Output path for the generated bindings.
       output: Output(dartFile: packageRoot.resolve('lib/add.g.dart')),
       // Optional. Where to look for header files.
       headers: Headers(entryPoints: [packageRoot.resolve('src/add.h')]),
       // Optional. What functions to generate bindings for.
       functions: Functions.includeSet({'add'}),
     ).generate();
   }
   

4. Run the script with dart run tool/ffigen.dart to generate the bindings. This will create the output lib/add.g.dart file, which can be imported by Dart code to access the C APIs. This command must be re-run whenever the FFIgen configuration (in tool/ffigen.dart) or the C sources for which bindings are generated change.

5. Import add.g.dart in your Dart app and call the generated methods to access the native C API:

   import 'add.g.dart';
   
   // ...
      
   void answerToLife() {
     print('The answer to the Ultimate Question is ${add(40, 2)}!');
   }
   

6. Before we can run the app, we need to compile the C sources. There are many ways to do that. For this example, we are using a build hook, which we define in hook/build.dart as follows. This build hook also requires a dependency on the hooks, code_assets, and native_toolchain_c helper packages, which we can add to our app by running dart pub add hooks code_assets native_toolchain_c.

   import 'package:code_assets/code_assets.dart';
   import 'package:hooks/hooks.dart';
   import 'package:native_toolchain_c/native_toolchain_c.dart';
      
   void main(List<String> args) async {
     await build(args, (input, output) async {
       if (input.config.buildCodeAssets) {
         final builder = CBuilder.library(
           name: 'add',
           assetName: 'add.g.dart',
           sources: ['src/add.c'],
         );
         await builder.run(input: input, output: output);
       }
     });
   }
   

That's it! Run your app with dart run to see it in action!

The complete and runnable example can be found in example/add.

More Examples #

The code_asset package contains comprehensive examples that showcase FFIgen. Additional examples that show how FFIgen can be used in different scenarios can also be found in the example directory.

Requirements #

LLVM (9+) must be installed on your system to use package:ffigen. Install it in the following way:

Linux #

1. Install libclangdev:
   • with apt-get: sudo apt-get install libclang-dev.
   • with dnf: sudo dnf install clang-devel.

Windows #

1. Install Visual Studio with C++ development support.
2. Install LLVM or winget install -e --id LLVM.LLVM.

macOS

1. Install Xcode.
2. Install Xcode command line tools: xcode-select --install.

YAML Configuration Reference #

In addition to the Dart API shown in the "Getting Started" section, FFIgen can also be configured via YAML. Support for the YAML configuration will be eventually phased out, and using the Dart API is recommended.

A YAML configuration can be either provided in the project's pubspec.yaml file under the key ffigen or via a custom YAML file. To generate bindings configured via YAML run either dart run ffigen if using the pubspec.yaml file or run dart run ffigen --config config.yaml where config.yaml is the path to your custom YAML file.

The following configuration options are available:

output: 'generated_bindings.dart'

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/'

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'
  as-int:
    # These enums will be generated as Dart integers instead of Dart enums
    include:
      - MyIntegerEnum
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'

include-unused-typedefs: true

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

comments:
  style: any
  length: full

structs:
  dependency-only: opaque
unions:
  dependency-only: opaque

sort: true

use-supported-typedefs: true

use-dart-handle: true

ignore-source-errors: true

dart run ffigen --ignore-source-errors

silence-enum-warning: true

exclude-all-by-default: true

preamble: |
  // ignore_for_file: camel_case_types, non_constant_identifier_names

library-imports:
  custom_lib: 'package:some_pkg/some_file.dart'

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:
  asset-id: 'package:some_pkg/asset' # Optional, was assetId in previous versions

language: 'objc'

output:
  ...
  objc-bindings: 'generated_bindings.m'

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:
    # Both package Uri and file paths are supported here.
    - 'package:some_pkg/symbols.yaml'
    - 'path/to/some/symbol_file.yaml'

external-versions:
  # See https://docs.flutter.dev/reference/supported-platforms.
  ios:
    min: 12.0.0
  macos:
    min: 10.14.0

Objective-C configuration options #

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-protocols:
  include:
    # Generates bindings for a specific protocol.
    - MyProtocol
objc-categories:
  include:
    # Generates bindings for a specific category.
    - MyCategory

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'

objc-interfaces:
  member-filter:
    MyInterface:
      include:
        - "someMethod:withArg:"
      # Since MyInterface has an include rule, all other methods
      # are excluded by default.
objc-protocols:
  member-filter:
    NS.*:  # Matches all protocols starting with NS.
      exclude:
        - copy.*  # Remove all copy methods from these protocols.
objc-categories:
  member-filter:
    MyCategory:
      include:
        - init.*  # Include all init methods.

include-transitive-objc-interfaces: true
include-transitive-objc-protocols: true

include-transitive-objc-categories: false

FAQ #

Can FFIgen be used for removing underscores or renaming declarations? #

FFIgen supports regexp-based renaming. The regexp must be a full match. For renaming you can use regexp groups ($1 means group 1).

To renaming clang_dispose_string to string_dispose we 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.

How to generate declarations only from particular headers? #

The default behavior 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.

Can FFIgen filter declarations by name? #

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.

How does FFIgen handle C Strings? #

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*.

How are unnamed enums handled? #

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'

How can I handle unexpected enum values? #

Native enums are, by default, generated into Dart enums with int get value and fromValue(int). This works well in the case that your enums values are known in advance and not going to change, and in return, you get the full benefits of Dart enums like exhaustiveness checking.

However, if a native library adds another possible enum value after you generate your bindings, and this new value is passed to your Dart code, this will result in an ArgumentError at runtime. To fix this, you can regenerate the bindings on the new header file, but if you wish to avoid this issue entirely, you can tell FFIgen to generate plain Dart integers for your enum instead. To do this, simply list your enum's name in the as-int section of your FFIgen config:

enums:
  as-int:
    include:
      - MyIntegerEnum
      - '*IntegerEnum'
    exclude:
      - FakeIntegerEnum

Functions that accept or return these enums will now accept or return integers instead, and it will be up to your code to map integer values to behavior and handle invalid values. But your code will be future-proof against new additions to the enums.

Why are some struct/union declarations generated even after excluded them in config? #

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

How to expose the native pointers? #

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 accessible 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'

How to get typedefs to Native and Dart type of a function? #

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 functions.
    exclude: # If you only use exclude, then everything not excluded is generated.
      - 'dispose'

How are Structs/Unions/Enums that are referred to via typedefs handled? #

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.

Why are some typedefs not generated? #

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.

How are macros handled? #

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.

What are these logs generated by FFIgen and how to fix them? #

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 using compiler-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's config) or other minor issues in the config file itself.
• Everything else can be safely ignored. Its 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]. The all and fine will print a ton of logs are meant for debugging purposes only.

How can type definitions be shared? #

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.

How does ObjC method filtering work? #

Methods and properties on ObjC interfaces and protocols can be filtered using the member-filter option under objc-interfaces and objc-protocols. For simplicity we'll focus on interface methods, but the same rules apply to properties and protocols. There are two parts to the filtering process: matching the interface, and then filtering the method.

The syntax of member-filter is a YAML map from a pattern to some include/exclude rules, and include and exclude are each a list of patterns.

objc-interfaces:
  member-filter:
    MyInterface:  # Matches an interface.
      include:
        - "someMethod:withArg:"  # Matches a method.
      exclude:
        - someOtherMethod  # Matches a method.

The interface matching logic is the same as the matching logic for the member-rename option:

• The pattern is compared against the original name of the interface (before any renaming is applied).
• The pattern may be a string or a regexp, but in either case they must match the entire interface name.
• If the pattern contains only alphanumeric characters, or _, it is treated as a string rather than a regex.
• String patterns take precedence over regexps. That is, if an interface matches both a regexp pattern, and a string pattern, it uses the string pattern's include/exclude rules.

The method filtering logic uses the same include/exclude rules as the rest of the config:

• include and exclude are a list of patterns.
• The patterns are compared against the original name of the method, before renaming.
• The patterns can be strings or regexps, but must match the entire method name.
• The method name is in ObjC selector syntax, which means that the method name and all the external parameter names are concatenated together with : characters. This is the same name you'll see in ObjC's API documentation.
• NOTE: Since the pattern must match the entire method name, and most ObjC method names end with a :, it's a good idea to surround the pattern with quotes, ". Otherwise, YAML will think you're defining a map key.
• If no include or exclude rules are defined, all methods are included, regardless of the top level exclude-all-by-default rule.
• If only include rules are defined, all non-matching methods are excluded.
• If only exclude rules are defined, all non-matching methods are included.
• If both include and exclude rules are defined, the exclude rules take precedence. That is, if a method name matches both an include rule and an exclude rule, the method is excluded. All non-matching methods are also excluded.

The property filtering rules live in the same objc-interfaces.member-filter option as the methods. There is no distinction between methods and properties in the filters. The protocol filtering rules live in objc-protocols.member-filter.

How do I generate bindings for Apple APIs? #

It can be tricky to locate header files containing Apple's ObjC frameworks, and the paths can vary between computers depending on which version of Xcode you are using and where it is installed. So FFIgen provides the following variable substitutions that can be used in the headers.entry-points list:

• $XCODE: Replaced with the result of xcode-select -p, which is the directory where Xcode's APIs are installed.
• $IOS_SDK: Replaced with xcrun --show-sdk-path --sdk iphoneos, which is the directory within $XCODE where the iOS SDK is installed.
• $MACOS_SDK: Replaced with xcrun --show-sdk-path --sdk macosx, which is the directory within $XCODE where the macOS SDK is installed.

For example:

headers:
  entry-points:
    - '$MACOS_SDK/System/Library/Frameworks/Foundation.framework/Headers/NSDate.h'