dart:ffi を使用した C 相互運用

Dart Native プラットフォームで実行される Dart モバイル、コマンドライン、およびサーバーアプリは、dart:ffi ライブラリを使用してネイティブ C API を呼び出し、ネイティブメモリの読み取り、書き込み、割り当て、および割り当て解除を行うことができます。FFI は 外部関数インターフェース の略です。同様の機能の他の用語には、ネイティブインターフェース および 言語バインディング があります。

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

   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. 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バインディングを作成するには時間がかかることがあります。DartにCヘッダーファイルからFFIラッパーを作成させるには、package:ffigenバインディングジェネレーターを使用します。

ネイティブアセット機能は、ネイティブコードに依存するDartパッケージの配布に関連する多くの問題を解決するはずです。これは、FlutterおよびスタンドアロンのDartアプリケーションのビルドに関与するさまざまなビルドシステムと統合するための統一されたフックを提供することにより実現します。

この機能は、Dartパッケージがネイティブコードに依存して使用する方法を簡素化するはずです。ネイティブアセットは、次のメリットを提供する必要があります。

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

ネイティブ実験にオプトインすると、flutter (run|build)およびdart (run|build)コマンドは、Dartコードとともにネイティブコードをビルドおよびバンドルします。

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:native_assets_cli APIリファレンスを参照してください。

実験を有効にしてフィードバックを提供する方法については、次のトラッキングイシューを参照してください。

• Dart ネイティブアセット
• Flutter ネイティブアセット

特に明記されていない限り、このサイトのドキュメントは Dart 3.5.3 を反映しています。ページは 2024-05-30 に最終更新されました。 ソースを表示または問題を報告する。