168 lines
6.3 KiB
Markdown
168 lines
6.3 KiB
Markdown
# Nyash Plugin System Documentation
|
||
|
||
## 🎯 Quick Start
|
||
|
||
**For new developers**: Start with [BID-FFI v1 実装仕様書](./bid-ffi-v1-actual-specification.md)
|
||
|
||
## 📚 Documentation Index
|
||
|
||
### 🟢 **Current & Accurate**
|
||
- **[bid-ffi-v1-actual-specification.md](./bid-ffi-v1-actual-specification.md)** - **主要仕様書**
|
||
- 実際に動作している実装をベースとした正確な仕様
|
||
- FileBoxプラグインで実証済み
|
||
- プラグイン開発者はここから始める
|
||
|
||
- **[../architecture/dynamic-plugin-flow.md](../architecture/dynamic-plugin-flow.md)** - **動的プラグインシステムの全体フロー** 🆕
|
||
- MIR→VM→Registry→プラグインの動的解決フロー
|
||
- コンパイル時決め打ちなし、実行時動的判定の仕組み
|
||
- nyash.tomlによる透過的な切り替え
|
||
|
||
- **[vm-plugin-integration.md](./vm-plugin-integration.md)** - **VM統合仕様書** 🆕
|
||
- VMバックエンドとプラグインシステムの統合
|
||
- BoxRef型による統一アーキテクチャ
|
||
- パフォーマンス最適化とエラーハンドリング
|
||
|
||
- **[plugin-tester.md](./plugin-tester.md)** - プラグイン診断ツール
|
||
- プラグインの動作確認とデバッグに使用
|
||
- `tools/plugin-tester`ツールの使用方法
|
||
|
||
- **[plugin_lifecycle.md](./plugin_lifecycle.md)** - ライフサイクル/RAII/シングルトン/ログ
|
||
- 共有ハンドル、scope終了時の扱い、`shutdown_plugins_v2()` の動作
|
||
- NetPlugin（HTTP/TCP）の並列E2E時の注意点
|
||
|
||
- **[net-plugin.md](./net-plugin.md)** - Netプラグイン（HTTP/TCP PoC）
|
||
- GET/POST、ヘッダ、Content-Length、環境変数によるログ
|
||
|
||
- **[returns-result.md](./returns-result.md)** - 可選のResultBox正規化
|
||
- `returns_result = true` で成功/失敗を `Ok/Err` に統一（段階導入推奨）
|
||
|
||
### ⚙️ 戻り値のResult化（B案サポート）
|
||
- `nyash.toml` のメソッド定義に `returns_result = true` を付けると、
|
||
- 成功: `Ok(value)` の `ResultBox` に包んで返す
|
||
- 失敗（BID負エラー）: `Err(ErrorBox(message))` を返す（例外にはしない）
|
||
|
||
```toml
|
||
[libraries."libnyash_example.so".ExampleBox.methods]
|
||
dangerousOp = { method_id = 10, returns_result = true }
|
||
```
|
||
|
||
未指定の場合は従来通り（成功=生値、失敗=例外として伝播）。
|
||
|
||
- **[filebox-bid-mapping.md](./filebox-bid-mapping.md)** - 参考資料
|
||
- FileBox APIとプラグイン実装の対応表
|
||
- API設計の参考として有用
|
||
|
||
### 🔄 **Migration & Reference**
|
||
- **[migration-guide.md](./migration-guide.md)** - 移行ガイド
|
||
- 古いドキュメントから現在の実装への移行方法
|
||
- ドキュメント状況の整理
|
||
|
||
### ⚠️ **Deprecated - 非推奨**
|
||
- **[ffi-abi-specification.md](./ffi-abi-specification.md)** - ❌ 理想案、未実装
|
||
- **[plugin-system.md](./plugin-system.md)** - ❌ 将来構想
|
||
- **[nyash-toml-v2-spec.md](./nyash-toml-v2-spec.md)** - ⚠️ 部分的に古い
|
||
|
||
## 🚀 For Plugin Developers
|
||
|
||
### 1. **Read the Specification**
|
||
```bash
|
||
# 主要仕様書を読む
|
||
cat docs/説明書/reference/plugin-system/bid-ffi-v1-actual-specification.md
|
||
```
|
||
|
||
### 2. **Study Working Example**
|
||
```bash
|
||
# FileBoxプラグインを参考にする
|
||
cd plugins/nyash-filebox-plugin
|
||
cat src/lib.rs
|
||
```
|
||
|
||
### 3. **Configure Your Plugin**
|
||
```bash
|
||
# 新スタイル（推奨）: 中央=nyash.toml（レジストリ最小） + 各プラグイン=nyash_box.toml（仕様書）
|
||
cat nyash.toml
|
||
cat plugins/<your-plugin>/nyash_box.toml
|
||
```
|
||
|
||
中央の `nyash.toml` 例（抜粋）
|
||
```toml
|
||
[plugins]
|
||
"libnyash_filebox_plugin" = "./plugins/nyash-filebox-plugin"
|
||
|
||
[plugin_paths]
|
||
search_paths = ["./plugins/*/target/release", "./plugins/*/target/debug"]
|
||
|
||
[box_types]
|
||
FileBox = 6
|
||
```
|
||
|
||
各プラグインの `nyash_box.toml` 例（抜粋）
|
||
```toml
|
||
[box]
|
||
name = "FileBox"
|
||
version = "1.0.0"
|
||
description = "File I/O operations Box"
|
||
|
||
[provides]
|
||
boxes = ["FileBox"]
|
||
|
||
[FileBox]
|
||
type_id = 6
|
||
|
||
[FileBox.methods.open]
|
||
id = 1
|
||
args = [ { name = "path", type = "string" }, { name = "mode", type = "string", default = "r" } ]
|
||
returns = { type = "void", error = "string" }
|
||
```
|
||
|
||
ロード時は `nyash_box.toml` が優先参照され、OS差（.so/.dll/.dylib、libプリフィックス）は自動吸収されます。従来の `[libraries]` 設定も当面は後方互換で有効です。
|
||
|
||
### 4. **Test Your Plugin**
|
||
```bash
|
||
# プラグインテスターで確認
|
||
cd tools/plugin-tester
|
||
cargo build --release
|
||
./target/release/plugin-tester check path/to/your/plugin.so
|
||
```
|
||
|
||
### 5. **nyash_box.toml テンプレ & スモーク** 🆕
|
||
- テンプレート: `docs/reference/plugin-system/nyash_box.toml.template`
|
||
- スモーク実行（VM・厳格チェックON）:
|
||
```bash
|
||
bash tools/smoke_plugins.sh
|
||
```
|
||
- 実行内容: Python デモと Integer デモを `NYASH_PLUGIN_STRICT=1` で起動し、nyash_box.toml 経路のロードと実行を確認
|
||
- 事前条件: `cargo build --release --features cranelift-jit` 済み、各プラグインも release ビルド済み
|
||
|
||
### 6. **プラグイン優先（ビルトイン上書き）設定** 🆕
|
||
- 既定では、ビルトインの実装が優先されます（安全第一）。
|
||
- プラグインで置き換えたい型（ConsoleBox など）がある場合は環境変数で上書き可能:
|
||
```bash
|
||
export NYASH_USE_PLUGIN_BUILTINS=1
|
||
export NYASH_PLUGIN_OVERRIDE_TYPES="ArrayBox,MapBox,ConsoleBox"
|
||
```
|
||
- 上記により、`new ConsoleBox()` などの生成がプラグイン経路に切替わります。
|
||
- 後方互換のため `[libraries]` にも対象プラグインを登録しておくと、解決の一貫性が高まります。
|
||
|
||
## 🔧 For Nyash Core Developers
|
||
|
||
### Implementation Files
|
||
- **[plugin_loader_v2.rs](../../../../src/runtime/plugin_loader_v2.rs)** - プラグインローダー実装
|
||
- **[nyash_toml_v2.rs](../../../../src/config/nyash_toml_v2.rs)** - 設定パーサー
|
||
- **[tlv.rs](../../../../src/bid/tlv.rs)** - TLVエンコーダー/デコーダー
|
||
|
||
### Next Steps
|
||
- **Phase 3**: MIR ExternCall → plugin system 接続実装
|
||
- **Future**: HTTP系ボックスのプラグイン化
|
||
|
||
## 📞 Support & Issues
|
||
|
||
- **Working Examples**: `plugins/nyash-filebox-plugin/`
|
||
- **Issues**: Report at [GitHub Issues](https://github.com/moe-charm/nyash/issues)
|
||
- **Configuration**: `nyash.toml` in project root
|
||
|
||
---
|
||
|
||
**Status**: Phase 2 Documentation Reorganization - Completed
|
||
**Last Updated**: 2025-08-20
|