FFIgen

FFIgen (the Foreign Function Interface generator) is a code generator tool that creates type-safe Dart bindings for C libraries and Apple frameworks (Objective-C and Swift). This allows calling Apple platform APIs (iOS and macOS) directly and synchronously from your Dart code.

Use FFIgen when you need to call C libraries, wrap compiled binaries (like C, C++, Rust, or Go), or interact directly with Objective-C and Swift frameworks on iOS and macOS.

For standard, cross-platform plugin development where you don't have critical data transfers, use Pigeon instead.

Generate bindings with FFIgen using the following steps:

1. Reference the native headers.
2. Write the FFIgen configuration script.
3. Generate the bindings by running FFIgen.
4. Call the generated code from Dart.

To start, identify the native header files or APIs you want to wrap. Then write a configuration script (typically tool/ffigen.dart). This configuration specifies where the header files are located and where to output the generated Dart code.

Next, run the configuration script (dart run tool/ffigen.dart), which parses the headers and generates the corresponding Dart bindings.

Last, import the generated Dart file into your app and call the functions directly. FFIgen communicates directly through the underlying FFI layer, so refer to the dart:ffi guide to learn how to manage native memory lifetimes and execute native calls without blocking the UI thread.

To explore a complete implementation of this flow, including how to configure the generator, refer to the official FFIgen examples.

The add example highlights the general flow with a toy native API (one function in a single header file).

The code_assets examples highlight real-world examples like system hostname lookups and audio playback.

For a production package on pub.dev that uses FFIgen to wrap Apple's NSURLSession API, check out package:cupertino_http (source on GitHub).

Some general considerations when working with FFIgen:

FFIgen uses libclang to parse headers. Always resolve compiler warnings logged during generation to prevent runtime crashes.

Dart has no equivalent of C macros (like #if TARGET_OS_IPHONE), so handle minor API variations using runtime Platform.isIOS checks.

Some Objective-C and Swift-specific pitfalls when working with FFIgen:

Objective-C methods are dynamically resolved. FFIgen automatically maps method selectors to Dart signatures, but verify selectors by reading the bindings if you're using heavily overloaded native methods.

Dart uses garbage collection while Objective-C uses reference counting. Passing Dart closures that close over native wrapper objects can easily create reference cycles and leak memory. To break these reference cycles, wrap the captured object in a WeakReference, as shown in the Objective-C memory management guide.

FFIgen wrappers enforce Dart static types, but the underlying Objective-C object might have a different runtime subclass, so Dart's is and as keywords won't work as expected. Use .isA() and .as() instead, as shown in the Objective-C runtime types guide.

UI-related Objective-C calls must run on the iOS main platform thread. Also, some types of callbacks can crash your app if they're executed on the wrong thread. To learn more, consult the Objective-C threading guide.

FFIgen interacts with Swift through Objective-C. Pure Swift features (such as structs, generics, or enums associated with values) aren't supported, and classes must be annotated with @objc. For pure Swift interop, explore the Dart team's experimental package:swiftgen package, or use Pigeon for production Swift plugins.

To learn about generating C, Objective-C, and Swift bindings with FFIgen, refer to the following resources:

• FFIgen package on pub.dev
• objective_c package on pub.dev
• Official FFIgen examples on GitHub