f85d3437c0cdf4ccde82679a7b472f9f8232ad31 - ffigen

commit	f85d3437c0cdf4ccde82679a7b472f9f8232ad31	[log] [tgz]
author	Prerak Mann <mannprerak2@gmail.com>	Fri Jun 04 15:46:50 2021 +0530
committer	GitHub <noreply@github.com>	Fri Jun 04 12:16:50 2021 +0200
tree	6aa0793e22d2bf2d6df8958f436be8cf3ade6491
parent	98b2d4ff29a8f054dce52a30b909f423d4cbd567 [diff]

Move from package:pedantic to pacakge:lints (#230)

59 files changed

tree: 6aa0793e22d2bf2d6df8958f436be8cf3ade6491

README.md

Binding generator for FFI bindings.

Note: ffigen only supports parsing C headers.

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

class NativeLibrary {
  final Pointer<T> Function<T extends NativeType>(String symbolName)
      _lookup;
  NativeLibrary(DynamicLibrary dynamicLibrary)
      : _lookup = dynamicLibrary.lookup;
  NativeLibrary.fromLookup(
      Pointer<T> Function<T extends NativeType>(String symbolName)
          lookup)
      : _lookup = lookup;

  int sum(int a, int b) {
    return _sum(a, b);
  }

  late final _sumPtr = _lookup<ffi.NativeFunction<ffi.Int32 Function(ffi.Int32, ffi.Int32)>>('sum');
  late final _sum = _sum_ptr.asFunction<int Function(int, int)>();
}

Using this package

Add ffigen under dev_dependencies in your pubspec.yaml.
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.

Installing LLVM

package:ffigen uses LLVM. Install LLVM (9+) in the following way.

ubuntu/linux

Install libclangdev - sudo apt-get install libclang-dev.

Windows

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

MacOS

Install Xcode.
Install LLVM - brew install llvm.

Configurations

Configurations can be provided in 2 ways-

In the project's pubspec.yaml file under the key ffigen.
Via a custom YAML file, then specify this file while running - dart run ffigen --config config.yaml

The following configuration options are available-

output: '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 and typedef.
    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'

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

dart-bool: true

use-dart-handle: true

preamble: |
  // ignore_for_file: camel_case_types, non_constant_identifier_names

typedef-map:
  'my_custom_type': 'IntPtr'
  'size_t': 'Int64'

# These are optional and also default,
# Omitting any and the default
# will be used.
size-map:
  char: 1
  unsigned char: 1
  short: 2
  unsigned short: 2
  int: 4
  unsigned int: 4
  long: 8
  unsigned long: 8
  long long: 8
  unsigned long long: 8
  enum: 4

Limitations

Multi OS support for types such as long. Issue #7

Trying out examples

cd examples/<example_u_want_to_run>, Run dart pub get.
Run dart run ffigen.

Running Tests

Dynamic library for some tests need to be built before running the examples.
cd test/native_test.
Run dart build_test_dylib.dart.

Run tests from the root of the package with dart run test.

Note: If llvm is not installed in one of the default locations, tests may fail.

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

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.

How to generate declarations only from particular headers?

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.

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 does ffigen handle C99 bool data type?

Although dart:ffi doesn't have a NativeType for bool, they can be implemented as Uint8. Ffigen generates dart bool for function parameters and return type by default. To disable this, and use int instead, set dart-bool: false in configurations.

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'

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 and typedefs?

By default all native pointers and typedefs are hidden, 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 and the native typedef are prefixed with Native_.

Example -

functions:
  symbol-address:
    include:
      - 'myFunc'
      - '.*' # Do this to expose all pointers.

How are Structs/Unions/Enums that are reffered 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.