make-moonbit-c-bindings

MoonBit C バインディングの作成

エンドツーエンドのバインディングプロジェクトでこのスキルを使用してください。実装前に、低レベルの FFI 構文、所有権アノテーション、moonbit.h の詳細についても moonbit-c-binding をお読みください。

クイックスタート

1. 一時ディレクトリに上流の C/C++ プロジェクトをクローンするか、内容を確認します。
2. 公開ヘッダー、生成される設定ヘッダー、ソースの配置、アロケーター API、ビルド時の型幅を特定します。
3. 安全な MoonBit API の範囲を決めます。すべての C API を機械的に公開しないでください。
4. templates/prepare.py を使ってソースをベンダーするか、それが明示的に望まれている場合に限り、システムライブラリにリンクします。
5. 薄い C ラッパー、非公開の MoonBit extern、そして安全な公開 MoonBit ラッパーを作成します。
6. moon check、ネイティブテスト、ASan、moon info、ベンダリングスクリプトの冪等性で検証します。

バインディングのアーキテクチャ

ライブラリに合わせて名前を調整しながら、次の配置を優先してください。足場を一から書き直すのではなく、同梱テンプレートを使って始めてください。

scripts/prepare.py          # optional: pinned upstream download + generated stubs
moon.mod.json               # preferred/supported native targets
src/moon.pkg                # native-stub list and file target gates
src/wrapper.c               # ABI normalization and ownership boundaries
src/ffi.mbt                 # private extern "c" declarations
src/<domain>.mbt            # safe public MoonBit API
src/<domain>_test.mbt       # regression tests
src/README.mbt.md           # tested documentation examples
README.md -> src/README.mbt.md

テンプレートの対応関係：

• templates/prepare.py -> scripts/prepare.py
• templates/moon.mod.json -> moon.mod.json
• templates/moon.pkg -> src/moon.pkg
• templates/wrapper.c -> src/wrapper.c
• templates/ffi.mbt -> src/ffi.mbt
• templates/api.mbt -> src/<domain>.mbt
• templates/README.mbt.md -> src/README.mbt.md

ASan の検証には、moonbit-c-binding/scripts/run-asan.py の付属ランナーを scripts/run-asan.py としてコピーするか、呼び出してください。そのランナーがプロジェクトに適用できない場合を除き、新しい ASan パッチ適用スクリプトを独自に作成しないでください。

ワークフロー

1. 上流プロジェクトを調査する

• まず公開ヘッダーを読みます。これらがバインディングの契約を定義します。
• プロジェクト固有の typedef（インデックス型、スカラー型、サイズ／カウント型、ハンドル型、列挙型の基底型、コールバックなど）の設定された幅を記録します。
• ライブラリの API と、CLI 専用、内部用、生成コード、テスト用のコードを分けます。
• メモリを確保する関数、入力を変更する関数、コールバックを保持する関数、または対応する destroy/free の呼び出しが必要な関数を探します。

2. MoonBit API を設計する

• 可能な場合は、生のポインターや配列ではなく、現在の C ライブラリに合ったドメイン固有の MoonBit 型を公開します。
• C に入る前に、形状とオプションの長さを検証します。
• 安全なラッパーで意味を維持できない場合は、安全でない C 機能や誤解を招く C 機能を省きます。
• C のステータスコードを MoonBit のエラーにマッピングし、出力パラメーターには構造化された結果レコードを返します。

3. ベンダーするか、リンクする

• ポータブルなパッケージでは、固定したリビジョンと再現可能なスクリプトを使い、C ソースを native-stub にベンダーします。
• MoonBit がスタブを 1 つのパッケージディレクトリに置く必要がある場合は、ソースをフラット化し、include を決定論的に書き換えます。
• 場当たり的なコンパイラーフラグに依存せず、設定済みヘッダーを生成します。
• ベンダリングスクリプトを再実行しても、追跡対象ファイルに差分が生じないことを確認します。

4. FFI 境界を構築する

• C ラッパーが ABI の正規化を担います。これには、型幅のアサーション、オプションのポインター変換、出力のコピー、C が確保したメモリの解放が含まれます。
• ffi.mbt では extern を非公開にし、#borrow / #owned を明示的に使用します。
• 公開 MoonBit ファイルから呼び出すのは安全なラッパー関数のみとし、生の C API は直接呼び出さないでください。
• オプション配列に余計な Boolean のセンチネルパラメーターを追加するのは避け、空の MoonBit 配列を使って、C 側で Moonbit_array_length を確認します。

5. 検証する

最低限、以下を実行します。

moon fmt
moon check --target all --warn-list +73
moon test --target native
python3 scripts/run-asan.py
moon info --target native
python3 scripts/prepare.py
git status --short

ネイティブ専用パッケージでは、moon.mod.json で "preferred-target": "native" と、実際にサポートする最小限の "supported-targets" の値を設定します。

必読のリファレンス

ライフサイクルと所有権; ベンダリングとパッケージ設定; テストとドキュメント。