ffigen

https://pub.dev/packages/ffigen
Admin
ffigen is a code generator for Dart FFI bindings that uses LibClang to automatically parse and...
Tokens:5,364
Snippets:91
Trust Score:9.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Configure LLVM Path in YAML

Source: https://pub.dev/packages/ffigen

Example of providing multiple search paths for the LLVM installation.

```yaml
llvm-path:
  - '/usr/local/opt/llvm'
  - 'C:\Program Files\llvm`
  - '/usr/lib/llvm-11'
```

--------------------------------

### Install LLVM on Windows

Source: https://pub.dev/packages/ffigen

Command to install LLVM on Windows using the winget package manager.

```bash
winget install -e --id LLVM.LLVM
```

--------------------------------

### Install libclang-dev on Linux

Source: https://pub.dev/packages/ffigen

Commands to install the required LLVM development headers on Linux systems.

```bash
sudo apt-get install libclang-dev
```

```bash
sudo dnf install clang-devel
```

--------------------------------

### Configure Output Path in YAML

Source: https://pub.dev/packages/ffigen

Examples of specifying the output path for generated bindings in a YAML configuration.

```yaml
output: 'generated_bindings.dart'
```

```yaml
output:
  bindings: 'generated_bindings.dart'
  ...
```

--------------------------------

### Install Xcode Command Line Tools on macOS

Source: https://pub.dev/packages/ffigen

Command to install the necessary Xcode command line tools for macOS.

```bash
xcode-select --install
```

--------------------------------

### Configure Header Entry Points

Source: https://pub.dev/packages/ffigen

Define the entry-points and include-directives for header files using glob syntax.

```yaml
headers:
  entry-points:
    - 'folder/**.h'
    - 'folder/specific_header.h'
  include-directives:
    - '**index.h'
    - '**/clang-c/**'
    - '/full/path/to/a/header.h'
```

--------------------------------

### Configure Compiler Options

Source: https://pub.dev/packages/ffigen

Pass compiler options to clang via configuration file or command line.

```yaml
compiler-opts:
  - '-I/usr/lib/llvm-9/include/'
```

```bash
dart run ffigen --compiler-opts "-I/headers
-L 'path/to/folder name/file'"
```

--------------------------------

### Configure output.symbol-file

Source: https://pub.dev/packages/ffigen

Generates a YAML file containing all types defined in the output, preferably using package URIs.

```yaml
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'
```

--------------------------------

### Configure output.objc-bindings

Source: https://pub.dev/packages/ffigen

Defines the file path for generated Objective-C code.

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

--------------------------------

### Specify Dylib Path

Source: https://pub.dev/packages/ffigen

Define the exact file path to the dynamic library.

```yaml
- '/usr/lib64/libclang.so'
```

--------------------------------

### Update Objective-C Library Initialization

Source: https://pub.dev/packages/ffigen/changelog

Adapting to the removal of the native library class in ObjC bindings by switching from a library instance to a direct DynamicLibrary open call.

```dart
final lib = FooNativeLib(DynamicLibrary.open('foo.dylib'));
```

```dart
DynamicLibrary.open('foo.dylib');
```

--------------------------------

### Implement C Function

Source: https://pub.dev/packages/ffigen

Source file implementing the logic for the C function.

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

--------------------------------

### Enable ffi-native

Source: https://pub.dev/packages/ffigen

Generates @Native bindings instead of using DynamicLibrary or lookup. Note that this feature is experimental.

```yaml
ffi-native:
  asset-id: 'package:some_pkg/asset' # Optional, was assetId in previous versions
```

--------------------------------

### Add file preamble

Source: https://pub.dev/packages/ffigen

Inject raw header content at the top of the generated file.

```yaml
preamble: |
  // ignore_for_file: camel_case_types, non_constant_identifier_names
```

--------------------------------

### Configure macOS C Standard Library Inclusion

Source: https://pub.dev/packages/ffigen

Toggle automatic inclusion of the C standard library path on macOS.

```yaml
compiler-opts-automatic:
  macos:
    include-c-standard-library: false
```

--------------------------------

### Sort bindings

Source: https://pub.dev/packages/ffigen

Enable alphabetical sorting of generated bindings.

```yaml
sort: true
```

--------------------------------

### Specify input language

Source: https://pub.dev/packages/ffigen

Sets the input language for binding generation. Defaults to 'c'.

```yaml
language: 'objc'
```

--------------------------------

### Import symbol-files

Source: https://pub.dev/packages/ffigen

Imports type definitions from existing symbol files for use across packages.

```yaml
import:
  symbol-files:
    # Both package Uri and file paths are supported here.
    - 'package:some_pkg/symbols.yaml'
    - 'path/to/some/symbol_file.yaml'
```

--------------------------------

### Add ffigen dependency via CLI

Source: https://pub.dev/packages/ffigen/install

Use these commands to add the package to your project's dependencies automatically.

```bash
$ dart pub add ffigen
```

```bash
$ flutter pub add ffigen
```

--------------------------------

### Define C Header API

Source: https://pub.dev/packages/ffigen

Header file defining the C function signature to be bound.

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

--------------------------------

### Add ffigen to pubspec.yaml

Source: https://pub.dev/packages/ffigen/install

Manually add the dependency to your pubspec.yaml file.

```yaml
dependencies:
  ffigen: ^21.0.0
```

--------------------------------

### Add module prefixes for Swift-wrapped Objective-C headers

Source: https://pub.dev/packages/ffigen

Specify a module name for classes when generating bindings from Objective-C headers that act as wrappers for Swift libraries.

```yaml
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'
```

--------------------------------

### Enable full code generation for transitive dependencies

Source: https://pub.dev/packages/ffigen

Set these flags to true to fully generate bindings for interfaces and protocols that are transitively depended upon.

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

--------------------------------

### Handle multiple protocols in ObjC

Source: https://pub.dev/packages/ffigen/changelog

Workaround for the limitation where only the first protocol of an id is used.

```dart
id<FooProtocol, BarProtocol> becomes FooProtocol. The FooProtocol.castFrom method can help work around issues this may cause.
```

--------------------------------

### Configure external-versions

Source: https://pub.dev/packages/ffigen

Filters out APIs deprecated in versions earlier than the specified minimums for iOS or macOS.

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

--------------------------------

### Configure Objective-C interface, protocol, and category filters

Source: https://pub.dev/packages/ffigen

Use these filters to include, exclude, or rename specific Objective-C declarations.

```yaml
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
```

--------------------------------

### Configure function leaf status

Source: https://pub.dev/packages/ffigen

Set isLeaf:true for specific functions to improve performance for short-running native calls.

```yaml
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'
```

--------------------------------

### Define Native Build Hook

Source: https://pub.dev/packages/ffigen

Build hook configuration to compile C sources into native assets.

```dart
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);
    }
  });
}
```

--------------------------------

### Configure FFI Generator Script

Source: https://pub.dev/packages/ffigen

Dart script to configure and execute the FfiGenerator for binding generation.

```dart
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();
}
```

--------------------------------

### Configure variadic arguments

Source: https://pub.dev/packages/ffigen

Define specific argument types for variadic functions that would otherwise be ignored.

```yaml
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]
```

--------------------------------

### Invoke Generated C Bindings

Source: https://pub.dev/packages/ffigen

Importing and calling the generated Dart bindings in an application.

```dart
import 'add.g.dart';

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

--------------------------------

### Expose Function Typedefs

Source: https://pub.dev/packages/ffigen

Generate Native and Dart typedefs for functions.

```yaml
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'
```

--------------------------------

### Ignore source errors

Source: https://pub.dev/packages/ffigen

Configure whether to ignore compiler warnings or errors during header parsing.

```yaml
ignore-source-errors: true
```

```bash
dart run ffigen --ignore-source-errors
```

--------------------------------

### Import ffigen in Dart

Source: https://pub.dev/packages/ffigen/install

Include this import statement in your Dart files to access the library.

```dart
import 'package:ffigen/ffigen.dart';
```

--------------------------------

### Set Generated Class Description

Source: https://pub.dev/packages/ffigen

Provide a Dart Doc comment for the generated class.

```yaml
description: 'Bindings to SQLite'
```

--------------------------------

### Specify library imports

Source: https://pub.dev/packages/ffigen

Define custom library imports for use within type mappings.

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

--------------------------------

### Generate Dart typedefs from C structs

Source: https://pub.dev/packages/ffigen/changelog

Demonstrates how C struct definitions are mapped to Dart FFI classes and typedefs.

```c
typedef struct A{
    ...
} TA, *PA;

TA func(PA ptr);
```

```dart
class A extends ffi.Struct {...}
typedef TA = A;
typedef PA = ffi.Pointer<A>;
TA func(PA ptr){...}
```

--------------------------------

### Filter and Rename Declarations

Source: https://pub.dev/packages/ffigen

Configure inclusion, exclusion, renaming, and symbol address exposure for various C declarations.

```yaml
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'
```

--------------------------------

### Filter methods and properties for Objective-C declarations

Source: https://pub.dev/packages/ffigen

Define member-level inclusion and exclusion rules for specific interfaces, protocols, or categories using regex patterns.

```yaml
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.
```

--------------------------------

### Enable typedef mapping

Source: https://pub.dev/packages/ffigen

Automatically map standard C typedefs to Dart FFI types.

```yaml
use-supported-typedefs: true
```

--------------------------------

### Configure comment extraction

Source: https://pub.dev/packages/ffigen

Control the style and length of documentation comments extracted from source headers.

```yaml
comments:
  style: any
  length: full
```

--------------------------------

### Configure dependency-only generation

Source: https://pub.dev/packages/ffigen

Set generation mode for structs and unions that are only used as dependencies.

```yaml
structs:
  dependency-only: opaque
unions:
  dependency-only: opaque
```

--------------------------------

### Map Dart_Handle

Source: https://pub.dev/packages/ffigen

Enable mapping of Dart_Handle to the Handle type.

```yaml
use-dart-handle: true
```

--------------------------------

### Filter and Rename Typedefs

Source: https://pub.dev/packages/ffigen

Configure inclusion and renaming for referred typedefs.

```yaml
typedefs:
  exclude:
    # Typedefs starting with `p` are not generated.
    - 'p.*'
  rename:
    # Removes '_' from beginning of a typedef.
    '_(.*)': '$1'
```

--------------------------------

### Exclude all by default

Source: https://pub.dev/packages/ffigen

Change default behavior to exclude all declarations unless explicitly included.

```yaml
exclude-all-by-default: true
```

--------------------------------

### Configure type-map

Source: https://pub.dev/packages/ffigen

Maps native types, typedefs, structs, and unions to specific Dart types and libraries.

```yaml
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'
```

--------------------------------

### Override struct packing

Source: https://pub.dev/packages/ffigen

Specify packing values for generated structs using regular expressions to match names.

```yaml
structs:
  pack:
    # Matches with the generated name.
    'NoPackStruct': none # No packing
    '.*': 1 # Pack all structs with value 1
```

--------------------------------

### Set Generated Class Name

Source: https://pub.dev/packages/ffigen

Specify the name of the generated Dart class.

```yaml
name: 'SQLite'
```

--------------------------------

### Include Unused Typedefs

Source: https://pub.dev/packages/ffigen

Enable generation of typedefs that are not referenced anywhere.

```yaml
include-unused-typedefs: true
```

--------------------------------

### Cast generated object to target protocol

Source: https://pub.dev/packages/ffigen/changelog

Use this cast when working with ObjCProtocolBuilder directly after calling build().

```dart
FooProtocol.castFrom(protocolBuilder.build())
```

--------------------------------

### Silence enum warnings

Source: https://pub.dev/packages/ffigen

Disable warnings related to enum integer type mimicking.

```yaml
silence-enum-warning: true
```

--------------------------------

### Disable automatic transitive category generation

Source: https://pub.dev/packages/ffigen

Set to false to prevent automatic inclusion of all categories that extend an included interface.

```yaml
include-transitive-objc-categories: false
```
Tokens:
Raw