Dart:ffi を使用した C の相互運用

Dart のモバイル、コマンドライン、およびサーバーアプリは、Dart Native プラットフォームで実行される場合、dart:ffi ライブラリを使用してネイティブ C API を呼び出したり、ネイティブメモリを読み書き、割り当て、解放したりできます。FFI は foreign function interface の略です。類似の機能には、native interface や language bindings という用語もあります。

API ドキュメントは、dart:ffi API リファレンスで利用可能です。

このガイドのサンプルを操作するには、完全な ffi サンプルディレクトリをダウンロードしてください。これには、dart:ffi ライブラリの使用方法を示す以下のサンプルが含まれています。

hello_world サンプルには、C ライブラリを呼び出すために必要な最小限のコードが含まれています。このサンプルは、前のセクションでダウンロードした samples/ffi にあります。

hello_world サンプルには、次のファイルが含まれています。

C ライブラリのビルドにより、libhello.dylib (macOS)、libhello.dll (Windows)、または libhello.so (Linux) という名前の動的ライブラリファイルを含むいくつかのファイルが作成されます。

動的ライブラリをビルドして Dart アプリを実行するためのコマンドは、次のシリーズに似ています。

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

dart:ffi ライブラリを使用して C 関数を呼び出す方法を学ぶには、hello.dart ファイルを確認してください。このセクションでは、このファイルの内容を説明します。

1. dart:ffi をインポートします。

   dart

   import 'dart:ffi' as ffi;

2. 動的ライブラリのパスを格納するために使用する path ライブラリをインポートします。

   dart

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

3. C 関数の FFI 型シグネチャを持つ typedef を作成します。
   dart:ffi ライブラリで最も使用される型については、ネイティブ型とのインターフェイスを参照してください。

   dart

   typedef hello_world_func = ffi.Void Function();

4. C 関数を呼び出す際に使用する変数の typedef を作成します。

   dart

   typedef HelloWorld = void Function();

5. 動的ライブラリのパスを格納する変数を格納します。

   dart

   final String libraryPath;
   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',
     );
   } else {
     libraryPath = path.join(
       Directory.current.path,
       'hello_library',
       'libhello.so',
     );
   }

6. C 関数を含む動的ライブラリを開きます。

   dart

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

7. C 関数への参照を取得し、変数に格納します。このコードは、ステップ 2 と 3 の typedefs、およびステップ 4 の動的ライブラリ変数を組み合わせて使用します。

   dart

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

8. C 関数を呼び出します。

   dart

   hello();

hello_world サンプルを理解したら、他の dart:ffi サンプルを参照してください。

ネイティブ C ライブラリをバンドル/パッケージ/配布してからロードする方法は、プラットフォームとライブラリの種類によって異なります。

方法については、以下のページとサンプルを参照してください。

• Android アプリ向けの Flutter dart:ffi
• iOS アプリ向けの Flutter dart:ffi
• macOS アプリ向けの Flutter dart:ffi
• dart:ffi サンプル

dart:ffi ライブラリは、NativeType を実装し、C のネイティブ型を表す複数の型を提供します。一部のネイティブ型はインスタンス化できます。その他のネイティブ型は、型シグネチャのマーカーとしてのみ使用できます。

次のネイティブ型は、型シグネチャのマーカーとして使用できます。これらまたはそのサブタイプは、Dart コードでインスタンス化できます。

以下のリストは、型シグネチャのマーカーとして機能するプラットフォームに依存しないネイティブ型を示しています。これらは Dart コードでインスタンス化できません。

また、ABI 固有のマーカーネイティブ型も多数あり、これらは AbiSpecificInteger を継承しています。これらの型が特定のプラットフォームでどのようにマッピングされるかについては、次の表でリンクされている API ドキュメントを参照してください。

大規模な API サーフェスでは、C コードと統合する Dart バインディングを作成するのは時間がかかる場合があります。C ヘッダーファイルから Dart が FFI ラッパーを作成するようにするには、package:ffigen バインディングジェネレーターを使用します。

Dart のビルドフック (旧称ネイティブアセット) を使用すると、パッケージに Dart ソースコード以上のものを含めることができます。パッケージには、実行時に透過的にビルド、バンドル、および利用可能になるネイティブコードアセットを含めることができるようになりました。

この機能により、Dart パッケージがネイティブコードに依存し、使用する方法が簡素化されます。

• hook/build.dart のパッケージのビルドフックを使用して、ネイティブコードをビルドするかバイナリを取得します。
• Dart と Flutter は、ビルドフックが報告する CodeAsset をバンドルします。
• 実行時に、assetId を使用して、宣言的な @Native<>() extern 関数を通じてコードアセットにアクセスします。

Flutter とスタンドアロン Dart は、アプリが使用するすべてのパッケージのネイティブコードを自動的にバンドルし、実行時に利用可能にします。これは、flutter (run|build) と dart (run|build) の両方で機能します。

native_add_library サンプルには、Dart パッケージで C コードをビルドしてバンドルするための最小限のコードが含まれています。

このサンプルには、次のファイルが含まれています。

Dart または Flutter プロジェクトが package:native_add_library に依存している場合、run、build、および test コマンドを実行すると、hook/build.dart ビルドフックが呼び出されます。native_add_app サンプルは、native_add_library の使用例を示しています。

API ドキュメントは、次のパッケージで入手できます。

• Dart FFI でのコードアセットのサポートについて学ぶには、Native および DefaultAsset の dart:ffi API リファレンスを参照してください。
• hook/build.dart ビルドフックについて学ぶには、package:hooks API リファレンスを参照してください。

フィードバックを提供する場合は、これらのトラッキング課題を参照してください。

• Dart ビルドフックとコードアセット
• Flutter ビルドフックとコードアセット