package:ffigen: Internal Working

Table of Contents -

  1. Overview
  2. LibClang
    1. Bindings
  3. Scripts
    1. ffigen.dart
  4. Components
    1. Config Provider
    2. Header Parser
    3. Code Generator

Overview

package:ffigen simplifies the process of generating dart:ffi bindings from C header files. It is simple to use, with the input being a small YAML config file. It requires LLVM (9+) to work. This document tries to give a complete overview of every component without going into too many details about every single class/file.

LibClang

package:ffigen binds to LibClang using dart:ffi for parsing C header files.

Bindings

The config file for generating bindings is tool/libclang_config.yaml. The bindings are generated to lib/src/header_parser/clang_bindings/clang_bindings.dart. These are used by Header Parser for calling libclang functions.

Scripts

ffigen.dart

This is the main entry point for the user- dart run ffigen.

  • Command-line options:
    • --verbose: Sets log level.
    • --config: Specifies a config file.
  • The internal modules are called by ffigen.dart in the following way:
  • ffigen.dart will try to find dynamic library in default locations. If that fails, the user must excplicitly specify location in ffigen's config under the key llvm-path.
    • It first creates a Config object from an input Yaml file. This is used by other modules.
    • The parse method is then invoked to generate a Library object.
    • Finally, the code is generated from the Library object to the specified file.

Components

Config Provider

The Config Provider holds all the configurations required by other modules.

  • Config Provider handles validation and extraction of configurations from YAML files.
  • Config Provider converts configurations to the format required by other modules. This object is passed around to every other module.

Header Parser

The Header Parser parses C header files and converts them into a Library object.

  • Header Parser handles including/excluding/renaming of declarations.
  • Header Parser also filters out any unimplemented or unsupported declarations before generating a Library object.

Code Generator

The Code Generator generates the actual string bindings.

  • Code generator handles all external name collisions, while internal name conflicts are handled by each specific Binding.
  • Code Generator also handles how workarounds for arrays and bools are generated.