C interop using dart:ffi

Dart mobile, command-line, and server apps running on the Dart Native platform can use the dart:ffi library to call native C APIs, and to read, write, allocate, and deallocate native memory. FFI stands for foreign function interface. Other terms for similar functionality include native interface and language bindings.

API documentation is available in the dart:ffi API reference.

To work with the examples in this guide, download the full ffi samples directory. It includes the following examples show how to use the dart:ffi library:

The hello_world example has the minimum necessary code for calling a C library. This example can be found in the samples/ffi you downloaded in the previous section.

The hello_world example has the following files:

Building the C library creates several files, including a dynamic library file named libhello.dylib (macOS), libhello.dll (Windows), or libhello.so (Linux).

The commands to build the dynamic library and execute the Dart app would resemble the following series.

$ cd hello_library
$ cmake .
...
$ make
...
$ cd ..
$ dart pub get
$ dart run hello.dart
Hello World

To learn how to call a C function using the dart:ffi library, review the hello.dart file. This section explains the contents of this file.

1. Import dart:ffi.

   dart

   import 'dart:ffi' as ffi;

2. Import the path library that you'll use to store the path of dynamic library.

   dart

   import 'dart:io' show Platform, Directory;
   import 'package:path/path.dart' as path;

3. Create a typedef with the FFI type signature of the C function.
   To learn about the most used types according to the dart:ffi library consult Interfacing with native types.

   dart

   typedef hello_world_func = ffi.Void Function();

4. Create a typedef for the variable to use when calling the C function.

   dart

   typedef HelloWorld = void Function();

5. Create a variable to store the path of the dynamic library.

   dart

   var libraryPath = path.join(Directory.current.path, 'hello_library',
       'libhello.so');
   if (Platform.isMacOS) {
     libraryPath = path.join(Directory.current.path, 'hello_library',
         'libhello.dylib');
   } else if (Platform.isWindows) {
     libraryPath = path.join(Directory.current.path, 'hello_library',
         'Debug', 'hello.dll');
   }

6. Open the dynamic library that contains the C function.

   dart

   final dylib = ffi.DynamicLibrary.open(libraryPath);

7. Get a reference to the C function, and put it into a variable. This code uses the typedefs from steps 2 and 3, along with the dynamic library variable from step 4.

   dart

   final HelloWorld hello = dylib
       .lookup<ffi.NativeFunction<hello_world_func>>('hello_world')
       .asFunction();

8. Call the C function.

   dart

   hello();

Once you understand the hello_world example, consult the other dart:ffi examples.

The method to bundle / package / distribute then load a native C library depends on the platform and library type.

To learn how, consult the following pages and examples.

• Flutter dart:ffi for Android apps
• Flutter dart:ffi for iOS apps
• Flutter dart:ffi for macOS apps
• dart:ffi examples

The dart:ffi library provides multiple types that implement NativeType and represent native types in C. You can instantiate some native types. Some other native types can be used only as markers in type signatures.

The following native types can be used as markers in type signatures. They or their subtypes can be instantiated in Dart code.

The following list shows which platform-agnostic native types that serve as markers in type signatures. They can't be instantiated in Dart code.

There are also many ABI specific marker native types that extend AbiSpecificInteger. To learn how these types map on specific platforms, consult the API documentation linked in the following table.

For large API surfaces, it can be time-consuming to write the Dart bindings that integrate with the C code. To have Dart create FFI wrappers from C header files, use the package:ffigen binding generator.

The Native Assets feature should resolve a number of issues associated with the distribution of Dart packages that depend on native code. It does so by providing uniform hooks for integrating with various build systems involved in building Flutter and standalone Dart applications.

This feature should simplify how Dart packages depend on and use native code. Native Assets should provide the following benefits:

• Build the native code or obtains the binaries using a package's hook/build.dart build hook.
• Bundle the native Asset that the build.dart build hook reports.
• Make native assets available at runtime through declarative @Native<>() extern functions using the assetId.

When you opt in to the native experiment, The flutter (run|build) and dart (run|build) commands build and bundle native code with the Dart code.

The native_add_library example includes the minimum code to build and bundle C code in a Dart package.

The example includes the following files:

When a Dart or Flutter project depends on package:native_add_library, it invokes the hook/build.dart build hook on run, build, and test commands. The native_add_app example showcases a use of native_add_library.

API documentation can be found for the following packages:

• To learn about native assets in Dart FFI, consult the dart:ffi API reference for Native and DefaultAsset.
• To learn about the hook/build.dart build hook, consult the package:native_assets_cli API reference.

To learn how to enable the experiment and provide feedback, consult these tracking issues:

• Dart native assets
• Flutter native assets