json-native: enable float roundtrip in parser (NUMBER => float by '.'/exp); expand roundtrip smoke with more numeric cases
This commit is contained in:
Selfhosting Dev
@ -349,7 +349,7 @@ box JsonParser {
|
|||||||
|
|
||||||
// ===== ユーティリティメソッド =====
|
// ===== ユーティリティメソッド =====
|
||||||
|
|
||||||
// 数値文字列を数値情報に変換（簡易版）
|
// 数値文字列を数値情報に変換（MVP）
|
||||||
// 返り値: MapBox { kind:"int"|"float", value: <int|float_str> }
|
// 返り値: MapBox { kind:"int"|"float", value: <int|float_str> }
|
||||||
convert_number(number_str) {
|
convert_number(number_str) {
|
||||||
local out = new MapBox()
|
local out = new MapBox()
|
||||||
@ -358,8 +358,11 @@ box JsonParser {
|
|||||||
out.set("value", StringUtils.parse_integer(number_str))
|
out.set("value", StringUtils.parse_integer(number_str))
|
||||||
return out
|
return out
|
||||||
}
|
}
|
||||||
// Float detection disabled in MVP pending StringUtils float API stabilization
|
// 浮動小数点: 小数点または指数表記を含むものは文字列のまま保持
|
||||||
if false {
|
if number_str.indexOf != null {
|
||||||
|
// indexOfが提供されていない環境向けフォールバック
|
||||||
|
}
|
||||||
|
if StringUtils.contains(number_str, ".") or StringUtils.contains(number_str, "e") or StringUtils.contains(number_str, "E") {
|
||||||
out.set("kind", "float")
|
out.set("kind", "float")
|
||||||
out.set("value", StringUtils.parse_float(number_str))
|
out.set("value", StringUtils.parse_float(number_str))
|
||||||
return out
|
return out
|
||||||
|
|||||||
@ -1,33 +1,5 @@
|
|||||||
# Merge Strategy — selfhosting‑dev × Cranelift branches
|
# Moved: Merge Strategy — branches
|
||||||
|
|
||||||
目的
|
このドキュメントは移動しました。
|
||||||
- selfhosting‑dev（VM/JIT 自己ホスト）と Cranelift 専用ブランチ（AOT/JIT‑AOT）を並行開発しつつ、衝突と複雑な解消作業を最小化する。
|
- 新しい場所: [development/engineering/merge-strategy.md](development/engineering/merge-strategy.md)
|
||||||
|
|
||||||
ブランチの役割
|
|
||||||
- `selfhosting-dev`: Ny→MIR→MIR-Interp→VM/JIT の安定化、ツール/スモーク、ドキュメント整備。
|
|
||||||
- `phase-15/self-host-aot-cranelift`（例）: Cranelift backend の実装・検証。
|
|
||||||
- `develop`: 定期同期の受け皿。`main` はリリース用。
|
|
||||||
|
|
||||||
方針（設計）
|
|
||||||
- 境界の明確化: Cranelift 固有コード（例: `src/jit/*`, `src/jit/rt.rs` など）は専用ブランチで集中的に変更。selfhosting‑dev は Runner/Interpreter/VM の公共 API に限定。
|
|
||||||
- Feature gate: 共有面に変更が必要な場合は `#[cfg(feature = "cranelift-jit")]` 等で分岐し、ABI/シグネチャ互換を保つ。
|
|
||||||
- ドキュメント分離: `CURRENT_TASK.md` はインデックス化し、詳細は `docs/phase-15/*` へトピックごとに分離（本運用により md の大規模衝突を回避）。
|
|
||||||
|
|
||||||
方針（運用）
|
|
||||||
- 同期リズム: selfhosting‑dev → develop へ週1回まとめPR。Cranelift 側も同周期で develop へリベース/マージ。
|
|
||||||
- 早期検知: 各PRで `rg` による衝突予兆チェック（ファイル/トークンベース）をテンプレに含める。
|
|
||||||
- rerere: `git config rerere.enabled true` を推奨し、同種の衝突解消を再利用。
|
|
||||||
- ラベル運用: `area:jit`, `area:vm`, `docs:phase-15`, `merge-risk:high` 等でレビュー優先度を明示。
|
|
||||||
|
|
||||||
ファイルオーナーシップ（推奨）
|
|
||||||
- Cranelift: `src/jit/**`, `src/jit/policy.rs`, `tools/*aot*`, `docs/phase-15/cranelift/**`
|
|
||||||
- Selfhost core: `src/interpreter/**`, `src/runner/**`, `dev/selfhosting/**`, `tools/smokes/v2/**`
|
|
||||||
- 共有/IR: `src/mir/**`, `src/parser/**` は変更時に両ブランチへ告知（PR説明で影響範囲を明記）。
|
|
||||||
|
|
||||||
実務Tips
|
|
||||||
- マージ用テンプレ（PR description）
|
|
||||||
- 目的 / 影響範囲 / 変更対象ファイル / 互換性 / リスクと回避策 / テスト項目
|
|
||||||
- 衝突抑止の小技
|
|
||||||
- md は章分割して別ファイルに参照化（本運用の通り）
|
|
||||||
- 大規模renameは単独PRで先行適用
|
|
||||||
- 共有インターフェイスは薄いアダプタで橋渡し（実装詳細は各ブランチ内）
|
|
||||||
|
|||||||
@ -1,43 +1,5 @@
|
|||||||
# Developer Quickstart
|
# Moved: Developer Quickstart
|
||||||
|
|
||||||
This quickstart summarizes the most common build/run/test flows when working on Nyash.
|
このドキュメントは移動しました。
|
||||||
|
- 新しい場所: [guides/build/dev-quickstart.md](guides/build/dev-quickstart.md)
|
||||||
|
|
||||||
See also
|
|
||||||
- Self‑hosting one‑pager: `docs/how-to/self-hosting.md`
|
|
||||||
|
|
||||||
## Build
|
|
||||||
- VM/JIT (Cranelift): `cargo build --release --features cranelift-jit`
|
|
||||||
- LLVM AOT: `LLVM_SYS_180_PREFIX=$(llvm-config-18 --prefix) cargo build --release --features llvm`
|
|
||||||
|
|
||||||
## Run
|
|
||||||
- Quick VM run: `./target/release/nyash --backend vm apps/APP/main.nyash`
|
|
||||||
- LLVM emit+link helper: `tools/build_llvm.sh apps/APP/main.nyash -o app`
|
|
||||||
|
|
||||||
## Smokes
|
|
||||||
- End‑to‑end LLVM smokes: `./tools/llvm_smoke.sh release`
|
|
||||||
- Use env toggles like `NYASH_LLVM_VINVOKE_RET_SMOKE=1`
|
|
||||||
|
|
||||||
## Syntax Sugar (Phase 12.7)
|
|
||||||
- Control via env: `NYASH_SYNTAX_SUGAR_LEVEL=none|basic|full`
|
|
||||||
- Or via `nyash.toml`:
|
|
||||||
```toml
|
|
||||||
[syntax]
|
|
||||||
sugar_level = "none" # or "basic" / "full"
|
|
||||||
```
|
|
||||||
|
|
||||||
## MIR Migration Notes
|
|
||||||
- Implementation currently enforces Core‑15 during migration with tests in place.
|
|
||||||
- Core‑13 is the final minimal kernel target. The final flip documentation is tracked under:
|
|
||||||
`docs/development/roadmap/mir/core-13/step-50/`.
|
|
||||||
|
|
||||||
## Testing
|
|
||||||
- Rust unit tests: `cargo test`
|
|
||||||
- Targeted: e.g., tokenizer/sugar config `cargo test --lib sugar_basic_test -- --nocapture`
|
|
||||||
|
|
||||||
## Acceptance Checklist (Feature Additions Pause)
|
|
||||||
- cargo check (workspace) passes
|
|
||||||
- Representative smokes are green:
|
|
||||||
- PyVM smokes: `tools/pyvm_stage2_smoke.sh`
|
|
||||||
- LLVM harness smokes: `tools/llvm_smoke.sh release`
|
|
||||||
- Macro goldens: `tools/ci_check_golden.sh`
|
|
||||||
- No spec changes (compat maintained); changes are minimal and local
|
|
||||||
|
|||||||
@ -1,276 +1,5 @@
|
|||||||
# Nyash ドキュメント再編成計画 📚
|
# Moved: Docs Reorganization Plan
|
||||||
|
|
||||||
## 📊 現状の分析結果
|
このドキュメントは移動しました。
|
||||||
|
- 新しい場所: [development/cleanup/docs-reorg/PLAN.md](development/cleanup/docs-reorg/PLAN.md)
|
||||||
|
|
||||||
### ファイル数統計
|
|
||||||
- **総ファイル数**: 283個（.md: 211個, .txt: 72個）
|
|
||||||
- **archive/**: 113ファイル（40%）
|
|
||||||
- **予定/**: 111ファイル（39%）
|
|
||||||
- **説明書/**: 41ファイル（14%）
|
|
||||||
- **その他**: 18ファイル（7%）
|
|
||||||
|
|
||||||
### 重複・散在ファイル
|
|
||||||
- **README系**: 18個（各ディレクトリに散在）
|
|
||||||
- **GETTING_STARTED**: 3バージョン存在
|
|
||||||
- **Phase関連**: 42ファイル（主に予定/native-plan/issues/）
|
|
||||||
- **AI相談記録**: 41ファイル（複数箇所に散在）
|
|
||||||
- **ビルドログ**: 13ファイル（archive各所）
|
|
||||||
|
|
||||||
## 🔍 現状の問題点
|
|
||||||
|
|
||||||
### 1. **構造の混乱**
|
|
||||||
- トップレベルに開発中/正式文書が混在
|
|
||||||
- `説明書/` と直下に同じような内容が散在
|
|
||||||
- `archive/` に無秩序に大量のファイル
|
|
||||||
|
|
||||||
### 2. **重複と不明確な階層**
|
|
||||||
- `説明書/reference/` と `reference/` が併存
|
|
||||||
- GETTING_STARTED.md が複数存在（通常版と2025版）
|
|
||||||
- MIR関連ドキュメントが複数箇所に分散
|
|
||||||
|
|
||||||
### 3. **AI相談記録の散在**
|
|
||||||
- gemini/chatgpt相談が archive/, トップ, design/decisions/ など複数箇所
|
|
||||||
- ビルドログも同様に散在
|
|
||||||
|
|
||||||
### 4. **開発フェーズ管理の複雑さ**
|
|
||||||
- Phase関連ファイルが `予定/native-plan/issues/` に大量
|
|
||||||
- 現在のタスクと将来計画が混在
|
|
||||||
|
|
||||||
## 📋 提案する新構造
|
|
||||||
|
|
||||||
```
|
|
||||||
docs/
|
|
||||||
├── README.md # ドキュメントマップ（どこに何があるか）
|
|
||||||
│
|
|
||||||
├── 📖 reference/ # 正式な技術仕様（安定版）
|
|
||||||
│ ├── README.md
|
|
||||||
│ ├── language/ # 言語仕様
|
|
||||||
│ │ ├── syntax.md # 構文リファレンス
|
|
||||||
│ │ ├── types.md # 型システム
|
|
||||||
│ │ ├── boxes.md # Box仕様
|
|
||||||
│ │ └── delegation.md # デリゲーション仕様
|
|
||||||
│ ├── architecture/ # アーキテクチャ
|
|
||||||
│ │ ├── overview.md # 全体設計
|
|
||||||
│ │ ├── mir.md # MIR仕様
|
|
||||||
│ │ ├── vm.md # VM仕様
|
|
||||||
│ │ └── plugins.md # プラグインシステム
|
|
||||||
│ └── api/ # API仕様
|
|
||||||
│ ├── builtin-boxes.md # ビルトインBox一覧
|
|
||||||
│ └── stdlib.md # 標準ライブラリ
|
|
||||||
│
|
|
||||||
├── 📚 guides/ # 利用者向けガイド
|
|
||||||
│ ├── README.md
|
|
||||||
│ ├── getting-started.md # はじめに（統一版）
|
|
||||||
│ ├── tutorials/ # チュートリアル
|
|
||||||
│ │ ├── hello-world.md
|
|
||||||
│ │ ├── basic-boxes.md
|
|
||||||
│ │ └── p2p-apps.md
|
|
||||||
│ ├── examples/ # サンプルコード
|
|
||||||
│ └── playground.md # プレイグラウンドガイド
|
|
||||||
│
|
|
||||||
├── 🔧 development/ # 開発者向け（進行中）
|
|
||||||
│ ├── README.md
|
|
||||||
│ ├── current/ # 現在の作業
|
|
||||||
│ │ ├── CURRENT_TASK.md
|
|
||||||
│ │ └── VM_CHANGES.md
|
|
||||||
│ ├── roadmap/ # 開発計画
|
|
||||||
│ │ ├── phases/ # Phase別計画
|
|
||||||
│ │ │ ├── phase-8/
|
|
||||||
│ │ │ ├── phase-9/
|
|
||||||
│ │ │ └── phase-10/
|
|
||||||
│ │ └── native-plan/ # ネイティブビルド計画
|
|
||||||
│ └── proposals/ # 提案・RFC
|
|
||||||
│ └── phase_9_78e.md
|
|
||||||
│
|
|
||||||
├── 🗄️ archive/ # アーカイブ（古い/歴史的文書）
|
|
||||||
│ ├── README.md # アーカイブの説明
|
|
||||||
│ ├── consultations/ # AI相談記録
|
|
||||||
│ │ ├── gemini/
|
|
||||||
│ │ ├── chatgpt/
|
|
||||||
│ │ └── codex/
|
|
||||||
│ ├── decisions/ # 過去の設計決定
|
|
||||||
│ ├── build-logs/ # ビルドログ
|
|
||||||
│ └── old-versions/ # 古いドキュメント
|
|
||||||
│
|
|
||||||
└── 🎨 assets/ # 画像・図表など
|
|
||||||
├── diagrams/
|
|
||||||
└── screenshots/
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔄 移行計画
|
|
||||||
|
|
||||||
### Phase 1: 基本構造作成（優先度: 高）
|
|
||||||
1. 新しいディレクトリ構造を作成
|
|
||||||
2. README.md でドキュメントマップ作成
|
|
||||||
3. 現在進行中のファイルを `development/current/` へ移動
|
|
||||||
|
|
||||||
### Phase 2: リファレンス整理（優先度: 高）
|
|
||||||
1. `説明書/reference/` の内容を `reference/` に統合
|
|
||||||
2. 重複ファイルの統合（GETTING_STARTED統一版作成）
|
|
||||||
3. MIR/VM関連ドキュメントを適切な場所に配置
|
|
||||||
|
|
||||||
### Phase 3: アーカイブ整理（優先度: 中）
|
|
||||||
1. AI相談記録を `archive/consultations/` に集約
|
|
||||||
2. ビルドログを `archive/build-logs/` に集約
|
|
||||||
3. 古いドキュメントを `archive/old-versions/` へ
|
|
||||||
|
|
||||||
### Phase 4: 開発ドキュメント整理（優先度: 中）
|
|
||||||
1. Phase関連ファイルを番号順に整理
|
|
||||||
2. 現在のタスクと将来計画を明確に分離
|
|
||||||
3. native-plan を整理して見やすく
|
|
||||||
|
|
||||||
## 💡 メリット
|
|
||||||
|
|
||||||
1. **明確な分類**: 利用者向け/開発者向け/アーカイブが明確
|
|
||||||
2. **検索性向上**: 必要な情報がどこにあるか分かりやすい
|
|
||||||
3. **メンテナンス性**: 新しいドキュメントの追加場所が明確
|
|
||||||
4. **バージョン管理**: 現在の仕様と過去の記録が分離
|
|
||||||
|
|
||||||
## 🤔 検討事項
|
|
||||||
|
|
||||||
### 日本語ディレクトリ名の変換案
|
|
||||||
現在の日本語ディレクトリを英語に統一：
|
|
||||||
- `説明書/` → `guides/` に内容を移動
|
|
||||||
- `予定/` → `development/roadmap/` に内容を移動
|
|
||||||
- 日本語ファイル名（.txt/.md）はそのまま維持（内容が日本語のため）
|
|
||||||
|
|
||||||
**理由**:
|
|
||||||
- 国際的な開発者にもアクセスしやすい
|
|
||||||
- パス指定時のエンコーディング問題を回避
|
|
||||||
- Git操作が簡単に
|
|
||||||
|
|
||||||
### 既存リンクの対応
|
|
||||||
- 多くの場所から参照されている可能性
|
|
||||||
- → **対策**: 移行期間は旧パスにシンボリックリンクまたはREADME配置
|
|
||||||
|
|
||||||
### 自動生成ドキュメント
|
|
||||||
- MIRダンプやベンチマーク結果など
|
|
||||||
- → **提案**: `development/generated/` または `archive/generated/` に配置
|
|
||||||
|
|
||||||
## 📝 実装順序の提案
|
|
||||||
|
|
||||||
### Step 1: 基本構造作成スクリプト
|
|
||||||
```bash
|
|
||||||
#!/bin/bash
|
|
||||||
# create_new_structure.sh
|
|
||||||
|
|
||||||
# 新構造の作成
|
|
||||||
mkdir -p reference/{language,architecture,api}
|
|
||||||
mkdir -p guides/{tutorials,examples}
|
|
||||||
mkdir -p development/{current,roadmap/{phases/{phase-8,phase-9,phase-10},native-plan},proposals}
|
|
||||||
mkdir -p archive/{consultations/{gemini,chatgpt,codex},decisions,build-logs,old-versions}
|
|
||||||
mkdir -p assets/{diagrams,screenshots}
|
|
||||||
|
|
||||||
# 各ディレクトリにREADME.mdを配置
|
|
||||||
echo "# Reference Documentation" > reference/README.md
|
|
||||||
echo "# User Guides" > guides/README.md
|
|
||||||
echo "# Development Documentation" > development/README.md
|
|
||||||
echo "# Archive" > archive/README.md
|
|
||||||
```
|
|
||||||
|
|
||||||
### Step 2: 優先移動ファイルリスト
|
|
||||||
1. **現在の作業ファイル**
|
|
||||||
- `CURRENT_TASK.md` → `development/current/`
|
|
||||||
- `CURRENT_VM_CHANGES.md` → `development/current/`
|
|
||||||
- `phase_9_78e_summary.md` → `development/current/`
|
|
||||||
|
|
||||||
2. **言語仕様**
|
|
||||||
- `LANGUAGE_REFERENCE_2025.md` → `reference/language/`
|
|
||||||
- `TECHNICAL_ARCHITECTURE_2025.md` → `reference/architecture/`
|
|
||||||
- `説明書/reference/` の内容 → `reference/` へ統合
|
|
||||||
|
|
||||||
3. **利用者ガイド**
|
|
||||||
- GETTING_STARTED系を統合 → `guides/getting-started.md`
|
|
||||||
- `説明書/guides/` → `guides/tutorials/`
|
|
||||||
|
|
||||||
### Step 3: 自動整理スクリプト案
|
|
||||||
```bash
|
|
||||||
#!/bin/bash
|
|
||||||
# reorganize_docs.sh
|
|
||||||
|
|
||||||
# Phase関連ファイルの整理
|
|
||||||
find 予定/native-plan/issues -name "phase_*.md" | while read f; do
|
|
||||||
phase=$(echo $f | grep -o 'phase_[0-9]\+' | head -1)
|
|
||||||
mkdir -p development/roadmap/phases/$phase
|
|
||||||
mv "$f" development/roadmap/phases/$phase/
|
|
||||||
done
|
|
||||||
|
|
||||||
# AI相談記録の集約
|
|
||||||
find . -name "*gemini*.txt" -exec mv {} archive/consultations/gemini/ \;
|
|
||||||
find . -name "*chatgpt*.txt" -exec mv {} archive/consultations/chatgpt/ \;
|
|
||||||
find . -name "*consultation*.txt" -exec mv {} archive/consultations/ \;
|
|
||||||
|
|
||||||
# ビルドログの集約
|
|
||||||
find . -name "*build*.log" -o -name "*build*.txt" -exec mv {} archive/build-logs/ \;
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🚀 実装提案
|
|
||||||
|
|
||||||
1. **まず `DOCUMENTATION_REORGANIZATION_PLAN.md` の承認**
|
|
||||||
2. **バックアップ作成**
|
|
||||||
```bash
|
|
||||||
tar -czf docs_backup_$(date +%Y%m%d).tar.gz docs/
|
|
||||||
```
|
|
||||||
3. **基本ディレクトリ構造の作成**（上記スクリプト）
|
|
||||||
4. **段階的移行**（優先度順）
|
|
||||||
5. **リンク切れチェック**
|
|
||||||
6. **最終確認とクリーンアップ**
|
|
||||||
|
|
||||||
## 📋 具体的な移行マッピング（主要ファイル）
|
|
||||||
|
|
||||||
### 現在のトップレベルファイル
|
|
||||||
```
|
|
||||||
docs/
|
|
||||||
├── CURRENT_TASK.md → development/current/
|
|
||||||
├── CURRENT_VM_CHANGES.md → development/current/
|
|
||||||
├── LANGUAGE_REFERENCE_2025.md → reference/language/
|
|
||||||
├── TECHNICAL_ARCHITECTURE_2025.md → reference/architecture/
|
|
||||||
├── Phase-9.75g-0-BID-FFI-*.md → development/roadmap/phases/phase-9/
|
|
||||||
├── README.md → そのまま（インデックスとして）
|
|
||||||
├── execution-backends.md → reference/architecture/
|
|
||||||
├── nyash_core_concepts.md → reference/language/
|
|
||||||
└── plugin-migration-*.md → reference/plugin-system/
|
|
||||||
```
|
|
||||||
|
|
||||||
### archiveの主要整理
|
|
||||||
```
|
|
||||||
archive/
|
|
||||||
├── chatgpt5/ → archive/consultations/chatgpt/
|
|
||||||
├── codex-analysis/ → archive/consultations/codex/
|
|
||||||
├── design/ → 一部をreference/へ、残りはarchive/decisions/
|
|
||||||
├── build_logs/ → archive/build-logs/に統合
|
|
||||||
└── *.txt (相談記録) → archive/consultations/へ分類
|
|
||||||
```
|
|
||||||
|
|
||||||
### 説明書/の再構成
|
|
||||||
```
|
|
||||||
説明書/
|
|
||||||
├── GETTING_STARTED*.md → guides/getting-started.md (統合版)
|
|
||||||
├── guides/ → guides/tutorials/
|
|
||||||
├── reference/ → reference/ (トップレベルに移動)
|
|
||||||
└── wasm/ → guides/wasm-guide/
|
|
||||||
```
|
|
||||||
|
|
||||||
## ✅ チェックリスト
|
|
||||||
|
|
||||||
移行前の確認事項：
|
|
||||||
- [ ] バックアップの作成
|
|
||||||
- [ ] 重要なドキュメントの特定
|
|
||||||
- [ ] 外部からのリンク確認（README、コード内のコメント等）
|
|
||||||
- [ ] CIスクリプトでのパス参照確認
|
|
||||||
|
|
||||||
移行後の確認事項：
|
|
||||||
- [ ] すべてのドキュメントが新構造に配置されているか
|
|
||||||
- [ ] 重複ファイルが統合されているか
|
|
||||||
- [ ] 各ディレクトリにREADME.mdがあるか
|
|
||||||
- [ ] リンク切れがないか
|
|
||||||
|
|
||||||
どうでしょうか？この計画で進めてよろしいですか？
|
|
||||||
|
|
||||||
もし承認いただければ、まず小規模なテスト移行から始めることもできます。
|
|
||||||
|
|
||||||
### 🎯 期待される効果
|
|
||||||
- **検索時間短縮**: 必要な情報への到達が3クリック以内に
|
|
||||||
- **メンテナンス性向上**: 新規ドキュメントの追加場所が明確
|
|
||||||
- **重複削減**: 18個のREADME → 5個程度に集約
|
|
||||||
- **整理度**: 283ファイル → 適切に分類された構造
|
|
||||||
@ -1,25 +1,5 @@
|
|||||||
# ExternCall Policy (Phase 15)
|
# Moved: ExternCall Reference
|
||||||
|
|
||||||
## Allowed Interfaces (minimal set)
|
このドキュメントは移動しました。
|
||||||
- `env.console.{log,warn,error,readLine}`
|
- 新しい場所: [reference/plugin-system/externcall.md](reference/plugin-system/externcall.md)
|
||||||
- `env.debug.trace`
|
|
||||||
- `env.system.{exit,now}` (if present)
|
|
||||||
|
|
||||||
All other host interactions should go through BoxCall (NyRT or plugins).
|
|
||||||
|
|
||||||
## Argument‑type‑based selection
|
|
||||||
- For `env.console.{log,warn,error}` and `env.debug.trace`:
|
|
||||||
- If the single argument is `i8*` (C string), call the C‑string variant:
|
|
||||||
- `nyash.console.log(i8*)`, `nyash.console.warn(i8*)`, `nyash.console.error(i8*)`
|
|
||||||
- `nyash.debug.trace(i8*)`
|
|
||||||
- Otherwise convert to `i64` and call the handle variant:
|
|
||||||
- `nyash.console.log_handle(i64)`, `nyash.console.warn_handle(i64)`, `nyash.console.error_handle(i64)`
|
|
||||||
- `nyash.debug.trace_handle(i64)`
|
|
||||||
|
|
||||||
## Rationale
|
|
||||||
- Keeps the AOT string path fast and avoids accidental `inttoptr` of handles.
|
|
||||||
- Avoids adding broad implicit conversions in ExternCall; selection is local and explicit.
|
|
||||||
|
|
||||||
## Non‑LLVM Backends
|
|
||||||
- VM, Cranelift JIT/AOT, and the interpreter may not implement this policy yet (not MIR14‑ready). LLVM is authoritative; other backends will align after stabilization.
|
|
||||||
|
|
||||||
|
|||||||
@ -1,70 +1,5 @@
|
|||||||
# llvmlite Harness（正式導入・Rust LLVM 対置運用）
|
# Moved: llvmlite Harness
|
||||||
|
|
||||||
Purpose
|
このドキュメントは移動しました。
|
||||||
- Python + llvmlite による高速・柔軟な LLVM 生成経路を提供（検証・プロトタイプと将来の主役）。
|
- 新しい場所: [reference/architecture/llvm-harness.md](reference/architecture/llvm-harness.md)
|
||||||
- Rust/inkwell 経路と並走し、代表ケースで機能同値（戻り値・検証）を維持。
|
|
||||||
|
|
||||||
Switch
|
|
||||||
- `NYASH_LLVM_USE_HARNESS=1` でハーネス優先（LLVM バックエンド入口から起動）。
|
|
||||||
|
|
||||||
Tracing
|
|
||||||
- `NYASH_LLVM_TRACE_FINAL=1` を設定すると、代表コール（`Main.node_json/3`, `Main.esc_json/1`, `main` 等）を標準出力へ簡易トレースします。
|
|
||||||
ON/OFF の最終 JSON 突合の補助に使用してください。
|
|
||||||
|
|
||||||
Protocol
|
|
||||||
- Input: MIR14 JSON（Rust 前段で Resolver/LoopForm 規約を満たした形）。
|
|
||||||
- Output: `.o` オブジェクト（既定: `NYASH_AOT_OBJECT_OUT` または `NYASH_LLVM_OBJ_OUT`）。
|
|
||||||
- 入口: `ny_main() -> i64`（戻り値は exit code 相当。必要時 handle 正規化を行う）。
|
|
||||||
|
|
||||||
CLI（crate）
|
|
||||||
- `crates/nyash-llvm-compiler` 提供の `ny-llvmc` は llvmlite ハーネスの薄ラッパーだよ。
|
|
||||||
- ダミー: `./target/release/ny-llvmc --dummy --out /tmp/dummy.o`
|
|
||||||
- JSON→.o: `./target/release/ny-llvmc --in mir.json --out out.o`
|
|
||||||
- JSON→EXE（新規）: `./target/release/ny-llvmc --in mir.json --emit exe --nyrt target/release --out app`
|
|
||||||
- `--nyrt <dir>` で `libnyrt.a` の位置を指定（省略時は `target/release`→`crates/nyrt/target/release` の順に探索）
|
|
||||||
- 追加フラグは `--libs "<flags>"` で渡せる（例: `--libs "-static"`）
|
|
||||||
- 既定のハーネススクリプトは `tools/llvmlite_harness.py`（`--harness` で上書き可）。
|
|
||||||
|
|
||||||
Quick Start
|
|
||||||
- 依存: `python3 -m pip install llvmlite`
|
|
||||||
- ダミー生成（配線検証）:
|
|
||||||
- `python3 tools/llvmlite_harness.py --out /tmp/dummy.o`
|
|
||||||
- NyRT（libnyrt.a）とリンクして EXE 化（例: `cc /tmp/dummy.o -L target/release -Wl,--whole-archive -lnyrt -Wl,--no-whole-archive -lpthread -ldl -lm -o app_dummy`）。
|
|
||||||
|
|
||||||
Wiring（Rust 側）
|
|
||||||
- `NYASH_LLVM_USE_HARNESS=1` のとき:
|
|
||||||
1) `--emit-mir-json <path>` 等で MIR(JSON) を出力
|
|
||||||
2) `python3 tools/llvmlite_harness.py --in <mir.json> --out <obj.o>` を起動
|
|
||||||
3) 成功後は通常のリンク手順（NyRT とリンク）
|
|
||||||
|
|
||||||
Tools / CLI（統合フロー）
|
|
||||||
- crate 直結の EXE 出力: `NYASH_LLVM_COMPILER=crate NYASH_LLVM_EMIT=exe tools/build_llvm.sh apps/tests/ternary_basic.nyash -o app`
|
|
||||||
- 環境変数 `NYASH_LLVM_NYRT` で NyRT の場所を、`NYASH_LLVM_LIBS` で追加フラグを指定できる。
|
|
||||||
- CLI から直接 EXE 出力（新規）:
|
|
||||||
- `./target/release/nyash --emit-exe tmp/app --backend mir apps/tests/ternary_basic.nyash`
|
|
||||||
- 追加オプション: `--emit-exe-nyrt <dir>` / `--emit-exe-libs "<flags>"`
|
|
||||||
|
|
||||||
Scope（Phase 15）
|
|
||||||
- 最小命令: Const/BinOp/Compare/Branch/Jump/Return（PHI は LLVM 側で合成）
|
|
||||||
- 文字列: NyRT Shim（`nyash.string.len_h`, `charCodeAt_h`, `concat_hh`, `eq_hh`）を declare → call
|
|
||||||
- NewBox/ExternCall/BoxCall: まずは固定シンボル／by-id を優先（段階導入）
|
|
||||||
- 目標: `apps/selfhost/tools/dep_tree_min_string.nyash` の `.ll verify green → .o` 安定化
|
|
||||||
|
|
||||||
Acceptance
|
|
||||||
- Harness ON/OFF で機能同値（戻り値/検証）。代表ケースで `.ll verify green` と `.o` 生成成功。
|
|
||||||
|
|
||||||
Notes
|
|
||||||
- 初版は固定 `ny_main` から開始してもよい（配線確認）。以降、MIR 命令を順次対応。
|
|
||||||
- ハーネスは自律（外部状態に依存しない）。エラーは即 stderr に詳細を出す。
|
|
||||||
|
|
||||||
PHI Policy（要点）
|
|
||||||
- Phase‑15 の既定は PHI‑on。MIR 側で SSA `Phi` を生成し、ハーネスは incoming の検証と最終 IR への反映だけを行う。
|
|
||||||
- レガシー互換のために PHI‑off が必要なケースでは `NYASH_MIR_NO_PHI=1` を明示してね（ハーネスは旧 edge-copy 互換ルートで補完する）。
|
|
||||||
- 詳細と背景は `docs/reference/mir/phi_policy.md` を参照。
|
|
||||||
|
|
||||||
Schema Validation（任意）
|
|
||||||
- JSON v0 のスキーマは `docs/reference/mir/json_v0.schema.json` にあるよ。
|
|
||||||
- 検証: `python3 tools/validate_mir_json.py <mir.json>`（要: `python3 -m pip install jsonschema`）。
|
|
||||||
|
|
||||||
Appendix: 静的リンクについて
|
|
||||||
- 生成 EXE は NyRT（libnyrt.a）を静的リンク。完全静的（-static）は musl 推奨（dlopen 不可になるため動的プラグインは使用不可）。
|
|
||||||
|
|||||||
@ -1,23 +1,5 @@
|
|||||||
# Plugin ABI (by-id / tagged) — Snapshot
|
# Moved: Plugin ABI
|
||||||
|
|
||||||
This summarizes the ABI surfaces used by LLVM in Phase 15. Details live in NyRT (`crates/nyrt`).
|
このドキュメントは移動しました。
|
||||||
|
- 新しい場所: [reference/abi/PLUGIN_ABI.md](reference/abi/PLUGIN_ABI.md)
|
||||||
## Fixed-arity by-id shims
|
|
||||||
- Integer-dominant: `i64 @nyash_plugin_invoke3_i64(i64 type_id, i64 method_id, i64 argc, i64 recv_h, i64 a1, i64 a2, i64 a3, i64 a4)`
|
|
||||||
- Float-dominant: `f64 @nyash_plugin_invoke3_f64(i64 type_id, i64 method_id, i64 argc, i64 recv_h, f64 a1, f64 a2, f64 a3, f64 a4)`
|
|
||||||
|
|
||||||
## Tagged shims (mixed types)
|
|
||||||
- Fixed (<=4 args): `i64 @nyash_plugin_invoke3_tagged_i64(i64 type_id, i64 method_id, i64 argc, i64 recv_h, i64 a1, i64 t1, i64 a2, i64 t2, i64 a3, i64 t3, i64 a4, i64 t4)`
|
|
||||||
- Vector (N args): `i64 @nyash.plugin.invoke_tagged_v_i64(i64 type_id, i64 method_id, i64 argc, i64 recv_h, i8* vals, i8* tags)`
|
|
||||||
|
|
||||||
Tag codes (minimal):
|
|
||||||
- 3=int, 5=float, 8=handle(ptr). Others are reserved/experimental.
|
|
||||||
|
|
||||||
## Return mapping (LLVM lowering)
|
|
||||||
- If destination is annotated as Integer/Bool → keep i64 as integer.
|
|
||||||
- If destination is String/Box/Array/Future/Unknown → cast i64 handle to opaque pointer for SSA flow; do not `inttoptr` where a C string is expected.
|
|
||||||
|
|
||||||
## Notes
|
|
||||||
- These ABIs are used by both built-ins (nyrt) and plugins for consistency.
|
|
||||||
- The LLVM backend is the reference; other backends will be aligned later.
|
|
||||||
|
|
||||||
|
|||||||
@ -1,145 +1,5 @@
|
|||||||
# Nyash ドキュメント再編成報告書 📋
|
# Moved: Reorganization Report
|
||||||
|
|
||||||
## 実行日時
|
このドキュメントは移動しました。
|
||||||
2025年8月20日 21:45
|
- 新しい場所: [development/cleanup/docs-reorg/REPORT.md](development/cleanup/docs-reorg/REPORT.md)
|
||||||
|
|
||||||
## 🎯 実施内容
|
|
||||||
|
|
||||||
### 1. バックアップ作成
|
|
||||||
- `docs_backup_20250820_214047.tar.gz` を作成済み
|
|
||||||
|
|
||||||
### 2. 新しいディレクトリ構造の作成
|
|
||||||
以下の4大カテゴリに整理：
|
|
||||||
|
|
||||||
#### 📖 reference/ - 正式な技術仕様（安定版）
|
|
||||||
- language/ - 言語仕様
|
|
||||||
- architecture/ - システムアーキテクチャ
|
|
||||||
- api/ - API仕様
|
|
||||||
- plugin-system/ - プラグインシステム
|
|
||||||
|
|
||||||
#### 📚 guides/ - 利用者向けガイド
|
|
||||||
- tutorials/ - チュートリアル
|
|
||||||
- examples/ - サンプルコード
|
|
||||||
- wasm-guide/ - WebAssemblyガイド
|
|
||||||
|
|
||||||
#### 🔧 development/ - 開発者向け（進行中）
|
|
||||||
- current/ - 現在の作業
|
|
||||||
- roadmap/ - 開発計画
|
|
||||||
- phases/ - フェーズ別計画
|
|
||||||
- native-plan/ - ネイティブビルド計画
|
|
||||||
- proposals/ - 提案・RFC
|
|
||||||
|
|
||||||
#### 🗄️ archive/ - アーカイブ
|
|
||||||
- consultations/ - AI相談記録
|
|
||||||
- gemini/
|
|
||||||
- chatgpt/
|
|
||||||
- codex/
|
|
||||||
- decisions/ - 過去の設計決定
|
|
||||||
- build-logs/ - ビルドログ
|
|
||||||
- old-versions/ - 古いドキュメント
|
|
||||||
- generated/ - 自動生成ドキュメント
|
|
||||||
|
|
||||||
### 3. ファイル移動状況
|
|
||||||
|
|
||||||
#### ✅ 完了した移動
|
|
||||||
- 基本的なディレクトリ構造の作成
|
|
||||||
- 各ディレクトリにREADME.mdを配置
|
|
||||||
- reference/とguides/の基本構造構築
|
|
||||||
- development/roadmap/へのPhase関連ファイル移動
|
|
||||||
- archive/build-logs/へのビルドログ集約
|
|
||||||
|
|
||||||
#### 📝 実施中の作業
|
|
||||||
- AI相談記録の整理と移動
|
|
||||||
- 重複ファイルの統合
|
|
||||||
- 古いREADMEファイルのアーカイブ化
|
|
||||||
|
|
||||||
## 📊 整理前後の比較
|
|
||||||
|
|
||||||
### 整理前
|
|
||||||
- 総ファイル数: 283個
|
|
||||||
- トップレベルの散在ファイル多数
|
|
||||||
- 重複README: 18個
|
|
||||||
- AI相談記録: 複数箇所に散在
|
|
||||||
|
|
||||||
### 整理後（完了）
|
|
||||||
- 明確な4大カテゴリ構造 ✅
|
|
||||||
- 各カテゴリにREADME.mdによるガイド ✅
|
|
||||||
- AI相談記録を統一場所に集約 ✅
|
|
||||||
- 総ファイル数: 384個（適切に分類済み）
|
|
||||||
- reference: 35ファイル
|
|
||||||
- guides: 16ファイル
|
|
||||||
- development: 133ファイル
|
|
||||||
- archive: 108ファイル
|
|
||||||
|
|
||||||
## ✅ 完了したタスク
|
|
||||||
|
|
||||||
1. **説明書/ディレクトリの統合** ✅
|
|
||||||
- 内容をreference/とguides/に分類・移動完了
|
|
||||||
|
|
||||||
2. **予定/ディレクトリの整理** ✅
|
|
||||||
- development/roadmap/への移動完了
|
|
||||||
|
|
||||||
3. **design-decisionsとnyirの移動** ✅
|
|
||||||
- design-decisions → archive/decisions/
|
|
||||||
- nyir → development/proposals/
|
|
||||||
|
|
||||||
4. **空ディレクトリのクリーンアップ** ✅
|
|
||||||
- 全ての空ディレクトリを削除済み
|
|
||||||
|
|
||||||
## 🚧 残タスク
|
|
||||||
|
|
||||||
1. **相互リンクの修正**
|
|
||||||
- 移動したファイルへの参照更新
|
|
||||||
- CLAUDE.mdの参照パス更新
|
|
||||||
|
|
||||||
2. **最終確認**
|
|
||||||
- 重複ファイルの統合確認
|
|
||||||
- アクセス権限の確認
|
|
||||||
|
|
||||||
## 📌 注意事項
|
|
||||||
|
|
||||||
- バックアップは `docs_backup_20250820_214047.tar.gz` に保存済み
|
|
||||||
- 重要なファイルは慎重に移動中
|
|
||||||
- CLAUDE.mdなどのルートファイルへの参照は要更新
|
|
||||||
|
|
||||||
## 🎯 次のステップ
|
|
||||||
|
|
||||||
1. 残りのファイル移動を完了
|
|
||||||
2. 空ディレクトリの削除
|
|
||||||
3. 相互リンクの確認と修正
|
|
||||||
4. 最終的な整合性チェック
|
|
||||||
5. CLAUDE.mdの参照更新
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 追加再編（2025-09-25、小規模・互換維持）
|
|
||||||
|
|
||||||
概要
|
|
||||||
- トップレベルに散在していたいくつかのカテゴリを、既存の4本柱へ段階的に集約しました（既定挙動は不変）。
|
|
||||||
|
|
||||||
主な移動
|
|
||||||
- architecture → reference/architecture
|
|
||||||
- phi-and-ssa.md を reference/architecture/ へ移動（旧パスに stub 追加）
|
|
||||||
- blueprints → development/design/blueprints
|
|
||||||
- strings-utf8-byte.md を移動（旧パスに stub 追加）
|
|
||||||
- design → development/design/legacy
|
|
||||||
- 設計ノート一式を legacy サブフォルダへ移動（旧フォルダに案内 README/stub 追加）
|
|
||||||
- proposals → development/proposals
|
|
||||||
- proposals/* を移動（旧パスに README/stub 追加）
|
|
||||||
- examples → guides/examples
|
|
||||||
- 例一式を移動（旧パスに README/stub 追加）
|
|
||||||
- status/golden → development/testing/golden
|
|
||||||
- ゴールデン出力を移動（旧パスに README 追加）
|
|
||||||
- tests → development/testing
|
|
||||||
- テストドキュメントを移動（旧パスに README 追加）
|
|
||||||
|
|
||||||
リンク更新
|
|
||||||
- docs/README.md の該当リンク（blueprints/design/proposals/using-loader）を最小修正
|
|
||||||
- docs/VM_README.md の examples 参照を guides/examples に更新
|
|
||||||
|
|
||||||
非対象
|
|
||||||
- docs/private/ 配下は今回の再編から除外（方針どおり）
|
|
||||||
|
|
||||||
受け入れチェック
|
|
||||||
- 既定挙動は不変、差分は最小
|
|
||||||
- 移動元ディレクトリに stub/README を配置し、後方互換を確保
|
|
||||||
|
|||||||
@ -1,107 +1,5 @@
|
|||||||
# Nyash VM 実行基盤ガイド（更新）
|
# Moved: Nyash VM Guide
|
||||||
|
|
||||||
- プラグインBox引数の最小対応を追加（TLV: BoxRef）
|
このドキュメントは移動しました。
|
||||||
- TLVタグ: 1=Bool, 2=I32, 3=I64, 4=F32, 5=F64, 6=String, 7=Bytes, 8=Handle(BoxRef)
|
- 新しい場所: [reference/architecture/vm.md](reference/architecture/vm.md)
|
||||||
- BoxRefはプラグインBox参照（type_id:u32, instance_id:u32）を8バイトでエンコード
|
|
||||||
- ユーザー定義/複雑なBoxは当面一部非対応（toStringフォールバック）。標準Boxはプラグイン経由で統一
|
|
||||||
|
|
||||||
現状のルーティング（Plugin-First）:
|
|
||||||
- User-defined: MIR関数（{Box}.{method}/{N}) にCall化（関数存在時）。それ以外はBoxCall。
|
|
||||||
- Plugin: BoxCall → PluginInvoke（method_idが解決可能）→ それ以外は名前解決で PluginHost.invoke_instance_method。
|
|
||||||
|
|
||||||
今後のタスク:
|
|
||||||
- VM側のfrom Parent.method対応（Builder/VM両対応）
|
|
||||||
- TLVの型拡張（Float/配列/BoxRef戻り値など）
|
|
||||||
|
|
||||||
## 🧮 VM実行統計（NYASH_VM_STATS / JSON）
|
|
||||||
|
|
||||||
VMは命令カウントと実行時間を出力できます。
|
|
||||||
|
|
||||||
使い方（CLIフラグ）:
|
|
||||||
```bash
|
|
||||||
# 人間向け表示
|
|
||||||
nyash --backend vm --vm-stats program.nyash
|
|
||||||
|
|
||||||
# JSON出力
|
|
||||||
nyash --backend vm --vm-stats --vm-stats-json program.nyash
|
|
||||||
```
|
|
||||||
|
|
||||||
環境変数（直接指定）:
|
|
||||||
```bash
|
|
||||||
NYASH_VM_STATS=1 ./target/debug/nyash --backend vm program.nyash
|
|
||||||
NYASH_VM_STATS=1 NYASH_VM_STATS_JSON=1 ./target/debug/nyash --backend vm program.nyash
|
|
||||||
# 代替: NYASH_VM_STATS_FORMAT=json
|
|
||||||
```
|
|
||||||
|
|
||||||
出力は `total`（総命令数）, `elapsed_ms`（経過時間）, `counts`（命令種別→回数）, `top20`（上位20種）を含みます。
|
|
||||||
|
|
||||||
## 既知の制約とTips（VM×プラグイン）
|
|
||||||
- Netプラグイン（HTTP）
|
|
||||||
- unreachable（接続不可/タイムアウト）は `Result.Err(ErrorBox)`。
|
|
||||||
- HTTP 404/500 は `Result.Ok(Response)`（アプリ側で `response.status` を確認）。
|
|
||||||
- デバッグ: `NYASH_NET_LOG=1 NYASH_NET_LOG_FILE=net_plugin.log`。
|
|
||||||
- FileBox
|
|
||||||
- `close()` は `Ok(Void)`。`match Ok(_)` で受けるか、戻り値を無視してよい。
|
|
||||||
- Handle（BoxRef）戻り
|
|
||||||
- TLV tag=8（type_id:u32, instance_id:u32）。Loaderが返り値typeに対応する `fini_method_id` を設定し `PluginBoxV2` を構築。
|
|
||||||
- `scope_tracker` がスコープ終了時に `fini()` を呼ぶ（メモリ安全）。
|
|
||||||
- 大きいボディ/多ヘッダー/タイムアウト
|
|
||||||
- 逐次拡張中。異常時の挙動は上記Result規約に従う。実行ログと `--vm-stats` を併用して診断。
|
|
||||||
- 反復タイムアウト: `local_tests/socket_repeated_timeouts.nyash` で `acceptTimeout/recvTimeout` の連続ケース確認
|
|
||||||
- BoxCallデバッグ: `NYASH_VM_DEBUG_BOXCALL=1` でBoxCallの受け手型・引数型・処理経路（enter/fastpath/unified）・結果型をstderr出力
|
|
||||||
- 例: `NYASH_VM_DEBUG_BOXCALL=1 ./target/release/nyash --backend vm local_tests/test_vm_array_getset.nyash`
|
|
||||||
|
|
||||||
## 🔧 BoxCallの統一経路（Phase 9.79b）
|
|
||||||
|
|
||||||
### method_id（スロット）によるBoxCall
|
|
||||||
- Builderが受け手型を推論できる場合、`BoxCall`に数値`method_id`（スロット）を付与。
|
|
||||||
- 低スロットはユニバーサル予約（0=toString, 1=type, 2=equals, 3=clone）。
|
|
||||||
- ユーザー定義Boxは宣言時にインスタンスメソッドへスロットを4番から順に予約（決定論的）。
|
|
||||||
|
|
||||||
### VMの実行経路（thunk + PIC）
|
|
||||||
- ユニバーサルスロット（0..3）はVMのfast-path thunkで即時処理。
|
|
||||||
- toString/type/equals/cloneの4種は受け手`VMValue`から直接評価。
|
|
||||||
- それ以外は以下の順で処理:
|
|
||||||
1. Mono-PIC（モノモーフィックPIC）直呼び: 受け手型×method（またはmethod_id）のキーでホットサイトを判定し、
|
|
||||||
`InstanceBox`は関数名キャッシュを使って `{Class}.{method}/{arity}` を直接呼び出す（閾値=8）。
|
|
||||||
2. 既存経路: `InstanceBox`はMIR関数へCall、それ以外は各Boxのメソッドディスパッチへフォールバック。
|
|
||||||
|
|
||||||
環境変数（デバッグ）:
|
|
||||||
```bash
|
|
||||||
NYASH_VM_DEBUG_BOXCALL=1 # BoxCallの入出力と処理経路を出力
|
|
||||||
NYASH_VM_PIC_DEBUG=1 # PICヒットのしきい値通過時にログ
|
|
||||||
```
|
|
||||||
|
|
||||||
今後の拡張:
|
|
||||||
- 一般`method_id`（ユーザー/プラグイン）に対するvtableスロット→thunk直呼び。
|
|
||||||
- PICのキャッシュ無効化（型version）と多相PICへの拡張（Phase 10）。
|
|
||||||
- SocketBox（VM）
|
|
||||||
- 基本API: `bind/listen/accept/connect/read/write/close/isServer/isConnected`
|
|
||||||
- タイムアウト: `acceptTimeout(ms)` は接続なしで `void`、`recvTimeout(ms)` は空文字を返す
|
|
||||||
- 簡易E2E: `local_tests/socket_timeout_server.nyash` と `socket_timeout_client.nyash`
|
|
||||||
- Void 比較の扱い（VM）
|
|
||||||
- `Void` は値を持たないため、`Eq/Ne` のみ有効。`Void == Void` は真、それ以外の型との `==` は偽（`!=` は真）。
|
|
||||||
- 順序比較（`<, <=, >, >=`）は `TypeError`。
|
|
||||||
|
|
||||||
## E2E 実行例（HTTPのResult挙動）
|
|
||||||
|
|
||||||
代表ケースを `tools/run_vm_stats.sh` で実行できます。`--vm-stats-json` により命令プロファイルも取得可能です。
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 別ターミナルでサーバ起動
|
|
||||||
./target/release/nyash local_tests/http_server_statuses.nyash
|
|
||||||
|
|
||||||
# クライアント（別ターミナル）
|
|
||||||
tools/run_vm_stats.sh local_tests/vm_stats_http_ok.nyash vm_stats_ok.json
|
|
||||||
tools/run_vm_stats.sh local_tests/vm_stats_http_404.nyash vm_stats_404.json
|
|
||||||
tools/run_vm_stats.sh local_tests/vm_stats_http_500.nyash vm_stats_500.json
|
|
||||||
|
|
||||||
# 到達不能（サーバ不要）
|
|
||||||
tools/run_vm_stats.sh local_tests/vm_stats_http_err.nyash vm_stats_err.json
|
|
||||||
```
|
|
||||||
|
|
||||||
期待されるResultモデル
|
|
||||||
- unreachable（接続不可/タイムアウト）: `Result.Err(ErrorBox)`
|
|
||||||
- 404/500 等のHTTPエラー: `Result.Ok(Response)`（アプリ側で `response.status` を評価）
|
|
||||||
|
|
||||||
詳細: `docs/reference/architecture/mir-to-vm-mapping.md` と `docs/guides/examples/http_result_patterns.md` を参照。
|
|
||||||
|
|||||||
6
docs/comparison/README.md
Normal file
6
docs/comparison/README.md
Normal file
@ -0,0 +1,6 @@
|
|||||||
|
# Moved: Comparison
|
||||||
|
|
||||||
|
比較記事は `docs/guides/comparison/` に移動しました。
|
||||||
|
|
||||||
|
- 代表: [nyash-vs-others.md](../guides/comparison/nyash-vs-others.md)
|
||||||
|
|
||||||
276
docs/development/cleanup/docs-reorg/PLAN.md
Normal file
276
docs/development/cleanup/docs-reorg/PLAN.md
Normal file
@ -0,0 +1,276 @@
|
|||||||
|
# Nyash ドキュメント再編成計画 📚
|
||||||
|
|
||||||
|
## 📊 現状の分析結果
|
||||||
|
|
||||||
|
### ファイル数統計
|
||||||
|
- **総ファイル数**: 283個（.md: 211個, .txt: 72個）
|
||||||
|
- **archive/**: 113ファイル（40%）
|
||||||
|
- **予定/**: 111ファイル（39%）
|
||||||
|
- **説明書/**: 41ファイル（14%）
|
||||||
|
- **その他**: 18ファイル（7%）
|
||||||
|
|
||||||
|
### 重複・散在ファイル
|
||||||
|
- **README系**: 18個（各ディレクトリに散在）
|
||||||
|
- **GETTING_STARTED**: 3バージョン存在
|
||||||
|
- **Phase関連**: 42ファイル（主に予定/native-plan/issues/）
|
||||||
|
- **AI相談記録**: 41ファイル（複数箇所に散在）
|
||||||
|
- **ビルドログ**: 13ファイル（archive各所）
|
||||||
|
|
||||||
|
## 🔍 現状の問題点
|
||||||
|
|
||||||
|
### 1. **構造の混乱**
|
||||||
|
- トップレベルに開発中/正式文書が混在
|
||||||
|
- `説明書/` と直下に同じような内容が散在
|
||||||
|
- `archive/` に無秩序に大量のファイル
|
||||||
|
|
||||||
|
### 2. **重複と不明確な階層**
|
||||||
|
- `説明書/reference/` と `reference/` が併存
|
||||||
|
- GETTING_STARTED.md が複数存在（通常版と2025版）
|
||||||
|
- MIR関連ドキュメントが複数箇所に分散
|
||||||
|
|
||||||
|
### 3. **AI相談記録の散在**
|
||||||
|
- gemini/chatgpt相談が archive/, トップ, design/decisions/ など複数箇所
|
||||||
|
- ビルドログも同様に散在
|
||||||
|
|
||||||
|
### 4. **開発フェーズ管理の複雑さ**
|
||||||
|
- Phase関連ファイルが `予定/native-plan/issues/` に大量
|
||||||
|
- 現在のタスクと将来計画が混在
|
||||||
|
|
||||||
|
## 📋 提案する新構造
|
||||||
|
|
||||||
|
```
|
||||||
|
docs/
|
||||||
|
├── README.md # ドキュメントマップ（どこに何があるか）
|
||||||
|
│
|
||||||
|
├── 📖 reference/ # 正式な技術仕様（安定版）
|
||||||
|
│ ├── README.md
|
||||||
|
│ ├── language/ # 言語仕様
|
||||||
|
│ │ ├── syntax.md # 構文リファレンス
|
||||||
|
│ │ ├── types.md # 型システム
|
||||||
|
│ │ ├── boxes.md # Box仕様
|
||||||
|
│ │ └── delegation.md # デリゲーション仕様
|
||||||
|
│ ├── architecture/ # アーキテクチャ
|
||||||
|
│ │ ├── overview.md # 全体設計
|
||||||
|
│ │ ├── mir.md # MIR仕様
|
||||||
|
│ │ ├── vm.md # VM仕様
|
||||||
|
│ │ └── plugins.md # プラグインシステム
|
||||||
|
│ └── api/ # API仕様
|
||||||
|
│ ├── builtin-boxes.md # ビルトインBox一覧
|
||||||
|
│ └── stdlib.md # 標準ライブラリ
|
||||||
|
│
|
||||||
|
├── 📚 guides/ # 利用者向けガイド
|
||||||
|
│ ├── README.md
|
||||||
|
│ ├── getting-started.md # はじめに（統一版）
|
||||||
|
│ ├── tutorials/ # チュートリアル
|
||||||
|
│ │ ├── hello-world.md
|
||||||
|
│ │ ├── basic-boxes.md
|
||||||
|
│ │ └── p2p-apps.md
|
||||||
|
│ ├── examples/ # サンプルコード
|
||||||
|
│ └── playground.md # プレイグラウンドガイド
|
||||||
|
│
|
||||||
|
├── 🔧 development/ # 開発者向け（進行中）
|
||||||
|
│ ├── README.md
|
||||||
|
│ ├── current/ # 現在の作業
|
||||||
|
│ │ ├── CURRENT_TASK.md
|
||||||
|
│ │ └── VM_CHANGES.md
|
||||||
|
│ ├── roadmap/ # 開発計画
|
||||||
|
│ │ ├── phases/ # Phase別計画
|
||||||
|
│ │ │ ├── phase-8/
|
||||||
|
│ │ │ ├── phase-9/
|
||||||
|
│ │ │ └── phase-10/
|
||||||
|
│ │ └── native-plan/ # ネイティブビルド計画
|
||||||
|
│ └── proposals/ # 提案・RFC
|
||||||
|
│ └── phase_9_78e.md
|
||||||
|
│
|
||||||
|
├── 🗄️ archive/ # アーカイブ（古い/歴史的文書）
|
||||||
|
│ ├── README.md # アーカイブの説明
|
||||||
|
│ ├── consultations/ # AI相談記録
|
||||||
|
│ │ ├── gemini/
|
||||||
|
│ │ ├── chatgpt/
|
||||||
|
│ │ └── codex/
|
||||||
|
│ ├── decisions/ # 過去の設計決定
|
||||||
|
│ ├── build-logs/ # ビルドログ
|
||||||
|
│ └── old-versions/ # 古いドキュメント
|
||||||
|
│
|
||||||
|
└── 🎨 assets/ # 画像・図表など
|
||||||
|
├── diagrams/
|
||||||
|
└── screenshots/
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🔄 移行計画
|
||||||
|
|
||||||
|
### Phase 1: 基本構造作成（優先度: 高）
|
||||||
|
1. 新しいディレクトリ構造を作成
|
||||||
|
2. README.md でドキュメントマップ作成
|
||||||
|
3. 現在進行中のファイルを `development/current/` へ移動
|
||||||
|
|
||||||
|
### Phase 2: リファレンス整理（優先度: 高）
|
||||||
|
1. `説明書/reference/` の内容を `reference/` に統合
|
||||||
|
2. 重複ファイルの統合（GETTING_STARTED統一版作成）
|
||||||
|
3. MIR/VM関連ドキュメントを適切な場所に配置
|
||||||
|
|
||||||
|
### Phase 3: アーカイブ整理（優先度: 中）
|
||||||
|
1. AI相談記録を `archive/consultations/` に集約
|
||||||
|
2. ビルドログを `archive/build-logs/` に集約
|
||||||
|
3. 古いドキュメントを `archive/old-versions/` へ
|
||||||
|
|
||||||
|
### Phase 4: 開発ドキュメント整理（優先度: 中）
|
||||||
|
1. Phase関連ファイルを番号順に整理
|
||||||
|
2. 現在のタスクと将来計画を明確に分離
|
||||||
|
3. native-plan を整理して見やすく
|
||||||
|
|
||||||
|
## 💡 メリット
|
||||||
|
|
||||||
|
1. **明確な分類**: 利用者向け/開発者向け/アーカイブが明確
|
||||||
|
2. **検索性向上**: 必要な情報がどこにあるか分かりやすい
|
||||||
|
3. **メンテナンス性**: 新しいドキュメントの追加場所が明確
|
||||||
|
4. **バージョン管理**: 現在の仕様と過去の記録が分離
|
||||||
|
|
||||||
|
## 🤔 検討事項
|
||||||
|
|
||||||
|
### 日本語ディレクトリ名の変換案
|
||||||
|
現在の日本語ディレクトリを英語に統一：
|
||||||
|
- `説明書/` → `guides/` に内容を移動
|
||||||
|
- `予定/` → `development/roadmap/` に内容を移動
|
||||||
|
- 日本語ファイル名（.txt/.md）はそのまま維持（内容が日本語のため）
|
||||||
|
|
||||||
|
**理由**:
|
||||||
|
- 国際的な開発者にもアクセスしやすい
|
||||||
|
- パス指定時のエンコーディング問題を回避
|
||||||
|
- Git操作が簡単に
|
||||||
|
|
||||||
|
### 既存リンクの対応
|
||||||
|
- 多くの場所から参照されている可能性
|
||||||
|
- → **対策**: 移行期間は旧パスにシンボリックリンクまたはREADME配置
|
||||||
|
|
||||||
|
### 自動生成ドキュメント
|
||||||
|
- MIRダンプやベンチマーク結果など
|
||||||
|
- → **提案**: `development/generated/` または `archive/generated/` に配置
|
||||||
|
|
||||||
|
## 📝 実装順序の提案
|
||||||
|
|
||||||
|
### Step 1: 基本構造作成スクリプト
|
||||||
|
```bash
|
||||||
|
#!/bin/bash
|
||||||
|
# create_new_structure.sh
|
||||||
|
|
||||||
|
# 新構造の作成
|
||||||
|
mkdir -p reference/{language,architecture,api}
|
||||||
|
mkdir -p guides/{tutorials,examples}
|
||||||
|
mkdir -p development/{current,roadmap/{phases/{phase-8,phase-9,phase-10},native-plan},proposals}
|
||||||
|
mkdir -p archive/{consultations/{gemini,chatgpt,codex},decisions,build-logs,old-versions}
|
||||||
|
mkdir -p assets/{diagrams,screenshots}
|
||||||
|
|
||||||
|
# 各ディレクトリにREADME.mdを配置
|
||||||
|
echo "# Reference Documentation" > reference/README.md
|
||||||
|
echo "# User Guides" > guides/README.md
|
||||||
|
echo "# Development Documentation" > development/README.md
|
||||||
|
echo "# Archive" > archive/README.md
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: 優先移動ファイルリスト
|
||||||
|
1. **現在の作業ファイル**
|
||||||
|
- `CURRENT_TASK.md` → `development/current/`
|
||||||
|
- `CURRENT_VM_CHANGES.md` → `development/current/`
|
||||||
|
- `phase_9_78e_summary.md` → `development/current/`
|
||||||
|
|
||||||
|
2. **言語仕様**
|
||||||
|
- `LANGUAGE_REFERENCE_2025.md` → `reference/language/`
|
||||||
|
- `TECHNICAL_ARCHITECTURE_2025.md` → `reference/architecture/`
|
||||||
|
- `説明書/reference/` の内容 → `reference/` へ統合
|
||||||
|
|
||||||
|
3. **利用者ガイド**
|
||||||
|
- GETTING_STARTED系を統合 → `guides/getting-started.md`
|
||||||
|
- `説明書/guides/` → `guides/tutorials/`
|
||||||
|
|
||||||
|
### Step 3: 自動整理スクリプト案
|
||||||
|
```bash
|
||||||
|
#!/bin/bash
|
||||||
|
# reorganize_docs.sh
|
||||||
|
|
||||||
|
# Phase関連ファイルの整理
|
||||||
|
find 予定/native-plan/issues -name "phase_*.md" | while read f; do
|
||||||
|
phase=$(echo $f | grep -o 'phase_[0-9]\+' | head -1)
|
||||||
|
mkdir -p development/roadmap/phases/$phase
|
||||||
|
mv "$f" development/roadmap/phases/$phase/
|
||||||
|
done
|
||||||
|
|
||||||
|
# AI相談記録の集約
|
||||||
|
find . -name "*gemini*.txt" -exec mv {} archive/consultations/gemini/ \;
|
||||||
|
find . -name "*chatgpt*.txt" -exec mv {} archive/consultations/chatgpt/ \;
|
||||||
|
find . -name "*consultation*.txt" -exec mv {} archive/consultations/ \;
|
||||||
|
|
||||||
|
# ビルドログの集約
|
||||||
|
find . -name "*build*.log" -o -name "*build*.txt" -exec mv {} archive/build-logs/ \;
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🚀 実装提案
|
||||||
|
|
||||||
|
1. **まず `DOCUMENTATION_REORGANIZATION_PLAN.md` の承認**
|
||||||
|
2. **バックアップ作成**
|
||||||
|
```bash
|
||||||
|
tar -czf docs_backup_$(date +%Y%m%d).tar.gz docs/
|
||||||
|
```
|
||||||
|
3. **基本ディレクトリ構造の作成**（上記スクリプト）
|
||||||
|
4. **段階的移行**（優先度順）
|
||||||
|
5. **リンク切れチェック**
|
||||||
|
6. **最終確認とクリーンアップ**
|
||||||
|
|
||||||
|
## 📋 具体的な移行マッピング（主要ファイル）
|
||||||
|
|
||||||
|
### 現在のトップレベルファイル
|
||||||
|
```
|
||||||
|
docs/
|
||||||
|
├── CURRENT_TASK.md → development/current/
|
||||||
|
├── CURRENT_VM_CHANGES.md → development/current/
|
||||||
|
├── LANGUAGE_REFERENCE_2025.md → reference/language/
|
||||||
|
├── TECHNICAL_ARCHITECTURE_2025.md → reference/architecture/
|
||||||
|
├── Phase-9.75g-0-BID-FFI-*.md → development/roadmap/phases/phase-9/
|
||||||
|
├── README.md → そのまま（インデックスとして）
|
||||||
|
├── execution-backends.md → reference/architecture/
|
||||||
|
├── nyash_core_concepts.md → reference/language/
|
||||||
|
└── plugin-migration-*.md → reference/plugin-system/
|
||||||
|
```
|
||||||
|
|
||||||
|
### archiveの主要整理
|
||||||
|
```
|
||||||
|
archive/
|
||||||
|
├── chatgpt5/ → archive/consultations/chatgpt/
|
||||||
|
├── codex-analysis/ → archive/consultations/codex/
|
||||||
|
├── design/ → 一部をreference/へ、残りはarchive/decisions/
|
||||||
|
├── build_logs/ → archive/build-logs/に統合
|
||||||
|
└── *.txt (相談記録) → archive/consultations/へ分類
|
||||||
|
```
|
||||||
|
|
||||||
|
### 説明書/の再構成
|
||||||
|
```
|
||||||
|
説明書/
|
||||||
|
├── GETTING_STARTED*.md → guides/getting-started.md (統合版)
|
||||||
|
├── guides/ → guides/tutorials/
|
||||||
|
├── reference/ → reference/ (トップレベルに移動)
|
||||||
|
└── wasm/ → guides/wasm-guide/
|
||||||
|
```
|
||||||
|
|
||||||
|
## ✅ チェックリスト
|
||||||
|
|
||||||
|
移行前の確認事項：
|
||||||
|
- [ ] バックアップの作成
|
||||||
|
- [ ] 重要なドキュメントの特定
|
||||||
|
- [ ] 外部からのリンク確認（README、コード内のコメント等）
|
||||||
|
- [ ] CIスクリプトでのパス参照確認
|
||||||
|
|
||||||
|
移行後の確認事項：
|
||||||
|
- [ ] すべてのドキュメントが新構造に配置されているか
|
||||||
|
- [ ] 重複ファイルが統合されているか
|
||||||
|
- [ ] 各ディレクトリにREADME.mdがあるか
|
||||||
|
- [ ] リンク切れがないか
|
||||||
|
|
||||||
|
どうでしょうか？この計画で進めてよろしいですか？
|
||||||
|
|
||||||
|
もし承認いただければ、まず小規模なテスト移行から始めることもできます。
|
||||||
|
|
||||||
|
### 🎯 期待される効果
|
||||||
|
- **検索時間短縮**: 必要な情報への到達が3クリック以内に
|
||||||
|
- **メンテナンス性向上**: 新規ドキュメントの追加場所が明確
|
||||||
|
- **重複削減**: 18個のREADME → 5個程度に集約
|
||||||
|
- **整理度**: 283ファイル → 適切に分類された構造
|
||||||
145
docs/development/cleanup/docs-reorg/REPORT.md
Normal file
145
docs/development/cleanup/docs-reorg/REPORT.md
Normal file
@ -0,0 +1,145 @@
|
|||||||
|
# Nyash ドキュメント再編成報告書 📋
|
||||||
|
|
||||||
|
## 実行日時
|
||||||
|
2025年8月20日 21:45
|
||||||
|
|
||||||
|
## 🎯 実施内容
|
||||||
|
|
||||||
|
### 1. バックアップ作成
|
||||||
|
- `docs_backup_20250820_214047.tar.gz` を作成済み
|
||||||
|
|
||||||
|
### 2. 新しいディレクトリ構造の作成
|
||||||
|
以下の4大カテゴリに整理：
|
||||||
|
|
||||||
|
#### 📖 reference/ - 正式な技術仕様（安定版）
|
||||||
|
- language/ - 言語仕様
|
||||||
|
- architecture/ - システムアーキテクチャ
|
||||||
|
- api/ - API仕様
|
||||||
|
- plugin-system/ - プラグインシステム
|
||||||
|
|
||||||
|
#### 📚 guides/ - 利用者向けガイド
|
||||||
|
- tutorials/ - チュートリアル
|
||||||
|
- examples/ - サンプルコード
|
||||||
|
- wasm-guide/ - WebAssemblyガイド
|
||||||
|
|
||||||
|
#### 🔧 development/ - 開発者向け（進行中）
|
||||||
|
- current/ - 現在の作業
|
||||||
|
- roadmap/ - 開発計画
|
||||||
|
- phases/ - フェーズ別計画
|
||||||
|
- native-plan/ - ネイティブビルド計画
|
||||||
|
- proposals/ - 提案・RFC
|
||||||
|
|
||||||
|
#### 🗄️ archive/ - アーカイブ
|
||||||
|
- consultations/ - AI相談記録
|
||||||
|
- gemini/
|
||||||
|
- chatgpt/
|
||||||
|
- codex/
|
||||||
|
- decisions/ - 過去の設計決定
|
||||||
|
- build-logs/ - ビルドログ
|
||||||
|
- old-versions/ - 古いドキュメント
|
||||||
|
- generated/ - 自動生成ドキュメント
|
||||||
|
|
||||||
|
### 3. ファイル移動状況
|
||||||
|
|
||||||
|
#### ✅ 完了した移動
|
||||||
|
- 基本的なディレクトリ構造の作成
|
||||||
|
- 各ディレクトリにREADME.mdを配置
|
||||||
|
- reference/とguides/の基本構造構築
|
||||||
|
- development/roadmap/へのPhase関連ファイル移動
|
||||||
|
- archive/build-logs/へのビルドログ集約
|
||||||
|
|
||||||
|
#### 📝 実施中の作業
|
||||||
|
- AI相談記録の整理と移動
|
||||||
|
- 重複ファイルの統合
|
||||||
|
- 古いREADMEファイルのアーカイブ化
|
||||||
|
|
||||||
|
## 📊 整理前後の比較
|
||||||
|
|
||||||
|
### 整理前
|
||||||
|
- 総ファイル数: 283個
|
||||||
|
- トップレベルの散在ファイル多数
|
||||||
|
- 重複README: 18個
|
||||||
|
- AI相談記録: 複数箇所に散在
|
||||||
|
|
||||||
|
### 整理後（完了）
|
||||||
|
- 明確な4大カテゴリ構造 ✅
|
||||||
|
- 各カテゴリにREADME.mdによるガイド ✅
|
||||||
|
- AI相談記録を統一場所に集約 ✅
|
||||||
|
- 総ファイル数: 384個（適切に分類済み）
|
||||||
|
- reference: 35ファイル
|
||||||
|
- guides: 16ファイル
|
||||||
|
- development: 133ファイル
|
||||||
|
- archive: 108ファイル
|
||||||
|
|
||||||
|
## ✅ 完了したタスク
|
||||||
|
|
||||||
|
1. **説明書/ディレクトリの統合** ✅
|
||||||
|
- 内容をreference/とguides/に分類・移動完了
|
||||||
|
|
||||||
|
2. **予定/ディレクトリの整理** ✅
|
||||||
|
- development/roadmap/への移動完了
|
||||||
|
|
||||||
|
3. **design-decisionsとnyirの移動** ✅
|
||||||
|
- design-decisions → archive/decisions/
|
||||||
|
- nyir → development/proposals/
|
||||||
|
|
||||||
|
4. **空ディレクトリのクリーンアップ** ✅
|
||||||
|
- 全ての空ディレクトリを削除済み
|
||||||
|
|
||||||
|
## 🚧 残タスク
|
||||||
|
|
||||||
|
1. **相互リンクの修正**
|
||||||
|
- 移動したファイルへの参照更新
|
||||||
|
- CLAUDE.mdの参照パス更新
|
||||||
|
|
||||||
|
2. **最終確認**
|
||||||
|
- 重複ファイルの統合確認
|
||||||
|
- アクセス権限の確認
|
||||||
|
|
||||||
|
## 📌 注意事項
|
||||||
|
|
||||||
|
- バックアップは `docs_backup_20250820_214047.tar.gz` に保存済み
|
||||||
|
- 重要なファイルは慎重に移動中
|
||||||
|
- CLAUDE.mdなどのルートファイルへの参照は要更新
|
||||||
|
|
||||||
|
## 🎯 次のステップ
|
||||||
|
|
||||||
|
1. 残りのファイル移動を完了
|
||||||
|
2. 空ディレクトリの削除
|
||||||
|
3. 相互リンクの確認と修正
|
||||||
|
4. 最終的な整合性チェック
|
||||||
|
5. CLAUDE.mdの参照更新
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 追加再編（2025-09-25、小規模・互換維持）
|
||||||
|
|
||||||
|
概要
|
||||||
|
- トップレベルに散在していたいくつかのカテゴリを、既存の4本柱へ段階的に集約しました（既定挙動は不変）。
|
||||||
|
|
||||||
|
主な移動
|
||||||
|
- architecture → reference/architecture
|
||||||
|
- phi-and-ssa.md を reference/architecture/ へ移動（旧パスに stub 追加）
|
||||||
|
- blueprints → development/design/blueprints
|
||||||
|
- strings-utf8-byte.md を移動（旧パスに stub 追加）
|
||||||
|
- design → development/design/legacy
|
||||||
|
- 設計ノート一式を legacy サブフォルダへ移動（旧フォルダに案内 README/stub 追加）
|
||||||
|
- proposals → development/proposals
|
||||||
|
- proposals/* を移動（旧パスに README/stub 追加）
|
||||||
|
- examples → guides/examples
|
||||||
|
- 例一式を移動（旧パスに README/stub 追加）
|
||||||
|
- status/golden → development/testing/golden
|
||||||
|
- ゴールデン出力を移動（旧パスに README 追加）
|
||||||
|
- tests → development/testing
|
||||||
|
- テストドキュメントを移動（旧パスに README 追加）
|
||||||
|
|
||||||
|
リンク更新
|
||||||
|
- docs/README.md の該当リンク（blueprints/design/proposals/using-loader）を最小修正
|
||||||
|
- docs/VM_README.md の examples 参照を guides/examples に更新
|
||||||
|
|
||||||
|
非対象
|
||||||
|
- docs/private/ 配下は今回の再編から除外（方針どおり）
|
||||||
|
|
||||||
|
受け入れチェック
|
||||||
|
- 既定挙動は不変、差分は最小
|
||||||
|
- 移動元ディレクトリに stub/README を配置し、後方互換を確保
|
||||||
@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
Scope
|
Scope
|
||||||
- Practical guide to LLVM lowering architecture and invariants used in Phase 15.
|
- Practical guide to LLVM lowering architecture and invariants used in Phase 15.
|
||||||
- Complements LOWERING_LLVM.md (rules), RESOLVER_API.md (value resolution), and LLVM_HARNESS.md (harness).
|
- Complements LOWERING_LLVM.md (rules), RESOLVER_API.md (value resolution), and docs/reference/architecture/llvm-harness.md (harness).
|
||||||
|
|
||||||
Module Layout
|
Module Layout
|
||||||
- `src/backend/llvm/compiler/codegen/`
|
- `src/backend/llvm/compiler/codegen/`
|
||||||
@ -33,5 +33,4 @@ Harness (optional)
|
|||||||
References
|
References
|
||||||
- LOWERING_LLVM.md — lowering rules and runtime calls
|
- LOWERING_LLVM.md — lowering rules and runtime calls
|
||||||
- RESOLVER_API.md — Resolver design and usage
|
- RESOLVER_API.md — Resolver design and usage
|
||||||
- LLVM_HARNESS.md — llvmlite harness interface and usage
|
- docs/reference/architecture/llvm-harness.md — llvmlite harness interface and usage
|
||||||
|
|
||||||
|
|||||||
33
docs/development/engineering/merge-strategy.md
Normal file
33
docs/development/engineering/merge-strategy.md
Normal file
@ -0,0 +1,33 @@
|
|||||||
|
# Merge Strategy — selfhosting‑dev × Cranelift branches
|
||||||
|
|
||||||
|
目的
|
||||||
|
- selfhosting‑dev（VM/JIT 自己ホスト）と Cranelift 専用ブランチ（AOT/JIT‑AOT）を並行開発しつつ、衝突と複雑な解消作業を最小化する。
|
||||||
|
|
||||||
|
ブランチの役割
|
||||||
|
- `selfhosting-dev`: Ny→MIR→MIR-Interp→VM/JIT の安定化、ツール/スモーク、ドキュメント整備。
|
||||||
|
- `phase-15/self-host-aot-cranelift`（例）: Cranelift backend の実装・検証。
|
||||||
|
- `develop`: 定期同期の受け皿。`main` はリリース用。
|
||||||
|
|
||||||
|
方針（設計）
|
||||||
|
- 境界の明確化: Cranelift 固有コード（例: `src/jit/*`, `src/jit/rt.rs` など）は専用ブランチで集中的に変更。selfhosting‑dev は Runner/Interpreter/VM の公共 API に限定。
|
||||||
|
- Feature gate: 共有面に変更が必要な場合は `#[cfg(feature = "cranelift-jit")]` 等で分岐し、ABI/シグネチャ互換を保つ。
|
||||||
|
- ドキュメント分離: `CURRENT_TASK.md` はインデックス化し、詳細は `docs/phase-15/*` へトピックごとに分離（本運用により md の大規模衝突を回避）。
|
||||||
|
|
||||||
|
方針（運用）
|
||||||
|
- 同期リズム: selfhosting‑dev → develop へ週1回まとめPR。Cranelift 側も同周期で develop へリベース/マージ。
|
||||||
|
- 早期検知: 各PRで `rg` による衝突予兆チェック（ファイル/トークンベース）をテンプレに含める。
|
||||||
|
- rerere: `git config rerere.enabled true` を推奨し、同種の衝突解消を再利用。
|
||||||
|
- ラベル運用: `area:jit`, `area:vm`, `docs:phase-15`, `merge-risk:high` 等でレビュー優先度を明示。
|
||||||
|
|
||||||
|
ファイルオーナーシップ（推奨）
|
||||||
|
- Cranelift: `src/jit/**`, `src/jit/policy.rs`, `tools/*aot*`, `docs/phase-15/cranelift/**`
|
||||||
|
- Selfhost core: `src/interpreter/**`, `src/runner/**`, `dev/selfhosting/**`, `tools/smokes/v2/**`
|
||||||
|
- 共有/IR: `src/mir/**`, `src/parser/**` は変更時に両ブランチへ告知（PR説明で影響範囲を明記）。
|
||||||
|
|
||||||
|
実務Tips
|
||||||
|
- マージ用テンプレ（PR description）
|
||||||
|
- 目的 / 影響範囲 / 変更対象ファイル / 互換性 / リスクと回避策 / テスト項目
|
||||||
|
- 衝突抑止の小技
|
||||||
|
- md は章分割して別ファイルに参照化（本運用の通り）
|
||||||
|
- 大規模renameは単独PRで先行適用
|
||||||
|
- 共有インターフェイスは薄いアダプタで橋渡し（実装詳細は各ブランチ内）
|
||||||
82
docs/development/refactoring/refactor-roadmap.md
Normal file
82
docs/development/refactoring/refactor-roadmap.md
Normal file
@ -0,0 +1,82 @@
|
|||||||
|
# Nyash Refactor Roadmap (Pre–Self-Hosting)
|
||||||
|
|
||||||
|
This document lists large modules, proposes safe splits/commonization, and outlines the MIR13 cleanup plan.
|
||||||
|
|
||||||
|
## Large Modules to Split
|
||||||
|
|
||||||
|
Targets are chosen by size and cohesion. Splits are incremental and build-preserving; move code in small steps and re-export in `mod.rs`.
|
||||||
|
|
||||||
|
- `src/mir/verification.rs` (~965 loc)
|
||||||
|
- Split into: `mir/verification/{mod.rs,basic.rs,types.rs,control_flow.rs,ownership.rs}`.
|
||||||
|
- First move leaf helpers and pass-specific checks; keep public API and `pub use` to avoid churn.
|
||||||
|
|
||||||
|
- `src/mir/builder.rs` (~930 loc)
|
||||||
|
- Split into: `mir/builder/{mod.rs,exprs.rs,stmts.rs,decls.rs,control_flow.rs}`.
|
||||||
|
- Extract expression/statement builders first. Keep tests (if any) colocated.
|
||||||
|
|
||||||
|
- `src/mir/instruction.rs` (~896 loc)
|
||||||
|
- Near-term: introduce `mir/instruction/{mod.rs,core.rs,ops.rs,calls.rs}` without changing the enum surface.
|
||||||
|
- Medium-term: migrate to MIR13 (see below) and delete legacy variants.
|
||||||
|
|
||||||
|
- `src/mir/optimizer.rs` (~875 loc)
|
||||||
|
- Split passes into: `mir/optimizer/{mod.rs,constant_folding.rs,dead_code.rs,inline.rs,type_inference.rs}`.
|
||||||
|
- Keep a simple pass runner that sequences the modules.
|
||||||
|
|
||||||
|
- `src/runner/mod.rs` (~885 loc)
|
||||||
|
- Extract modes into `runner/modes/{vm.rs,jit.rs,mir_interpreter.rs,llvm.rs}` if not already, and move glue to `runner/lib.rs`.
|
||||||
|
- Centralize CLI arg parsing in a dedicated module.
|
||||||
|
|
||||||
|
- `src/backend/vm_instructions/boxcall.rs` (~881 loc)
|
||||||
|
- Group by box domain: `boxcall/{array.rs,map.rs,ref.rs,weak.rs,plugin.rs,core.rs}`.
|
||||||
|
- Long-term: most of these become `BoxCall` handlers driven by method ID tables.
|
||||||
|
|
||||||
|
## MIR13 Cleanup Plan
|
||||||
|
|
||||||
|
A large portion of pre-MIR13 variants remain. Current occurrences:
|
||||||
|
|
||||||
|
- ArrayGet: 11, ArraySet: 11
|
||||||
|
- RefNew: 8, RefGet: 15, RefSet: 17
|
||||||
|
- TypeCheck: 13, Cast: 13
|
||||||
|
- PluginInvoke: 14, Copy: 13, Debug: 8, Print: 10, Nop: 9, Throw: 12, Catch: 13, Safepoint: 14
|
||||||
|
|
||||||
|
Phased migration (mechanical, testable per phase):
|
||||||
|
|
||||||
|
1) Introduce shims
|
||||||
|
- Add `BoxCall` helpers covering array/ref/weak/map ops and plugin methods.
|
||||||
|
- Add `TypeOp::{Check,Cast}` modes to map legacy `TypeCheck/Cast`.
|
||||||
|
|
||||||
|
2) Replace uses (non-semantic changes)
|
||||||
|
- Replace within: `backend/dispatch.rs`, `backend/mir_interpreter.rs`, `backend/cranelift/*`, `backend/wasm/codegen.rs`, `mir/printer.rs`, tests.
|
||||||
|
- Keep legacy variants in enum but mark Deprecated for a short period.
|
||||||
|
|
||||||
|
3) Tighten verification/optimizer
|
||||||
|
- Update `verification.rs` to reason about `BoxCall/TypeOp` only.
|
||||||
|
- Update optimizer patterns (e.g., fold Copy → Load/Store; drop Nop/Safepoint occurrences).
|
||||||
|
|
||||||
|
4) Delete legacy variants
|
||||||
|
- Remove `ArrayGet/Set, RefNew/Get/Set, PluginInvoke, TypeCheck, Cast, Copy, Debug, Print, Nop, Throw, Catch, Safepoint`.
|
||||||
|
- Update discriminant printer and state dumps accordingly.
|
||||||
|
|
||||||
|
Use `tools/mir13-migration-helper.sh` to generate per-file tasks and verify.
|
||||||
|
|
||||||
|
## Commonization Opportunities
|
||||||
|
|
||||||
|
- Backend dispatch duplication
|
||||||
|
- `backend/dispatch.rs`, `backend/vm.rs`, and Cranelift JIT lowerings handle overlapping instruction sets. Centralize instruction semantics interfaces (traits) and keep backend-specific execution and codegen in adapters.
|
||||||
|
|
||||||
|
- Method ID resolution
|
||||||
|
- `runtime/plugin_loader_v2` and backend call sites both compute/lookup method IDs. Provide a single resolver module with caching shared by VM/JIT/LLVM.
|
||||||
|
|
||||||
|
- CLI/runtime bootstrap
|
||||||
|
- Move repeated plugin host init/logging messages into a small `runtime/bootstrap.rs` with a single `init_plugins(&Config)` entry point used by all modes.
|
||||||
|
|
||||||
|
## Suggested Order of Work
|
||||||
|
|
||||||
|
1. Split `mir/verification` and `mir/builder` into submodules (no behavior changes).
|
||||||
|
2. Add `BoxCall` shims and `TypeOp` modes; replace printer/dispatch/codegen uses.
|
||||||
|
3. Update verification/optimizer for the unified ops.
|
||||||
|
4. Delete legacy variants and clean up dead code.
|
||||||
|
5. Tackle `runner/mod.rs` and `backend/vm_instructions/boxcall.rs` splits.
|
||||||
|
|
||||||
|
Each step should compile independently and run `tools/smoke_vm_jit.sh` to validate VM/JIT basics.
|
||||||
|
|
||||||
@ -121,7 +121,7 @@ void ny_root_remove(ny_handle h);
|
|||||||
|
|
||||||
- MIRの**Call統一**（進行中の`Call{callee: Callee}`方式）をLLVMでも厳守
|
- MIRの**Call統一**（進行中の`Call{callee: Callee}`方式）をLLVMでも厳守
|
||||||
- **型・スロットIDの決定をFrontend時点で確定**させ、**Codegenでは機械的に`ny_call_method(id)`を吐くだけ**にする
|
- **型・スロットIDの決定をFrontend時点で確定**させ、**Codegenでは機械的に`ny_call_method(id)`を吐くだけ**にする
|
||||||
- Pythonルート（llvmliteハーネス）も同じABIに揃え、**NyRT名称のdeclareを撲滅**（`LLVM_HARNESS.md`の"NyRT shim"項を置換）
|
- Pythonルート（llvmliteハーネス）も同じABIに揃え、**NyRT名称のdeclareを撲滅**（`docs/reference/architecture/llvm-harness.md`の"NyRT shim"項を置換）
|
||||||
|
|
||||||
## GC設計（設計の要点）
|
## GC設計（設計の要点）
|
||||||
|
|
||||||
@ -209,4 +209,4 @@ Kernelに残す。LLVMは**root/safepoint**を挿入するだけ。将来GC実
|
|||||||
- **直接的継続**: プラグインファクトリー完成の自然な次段階
|
- **直接的継続**: プラグインファクトリー完成の自然な次段階
|
||||||
- **Phase 2.4候補**: Phase 2.3（builtin削除）の発展形
|
- **Phase 2.4候補**: Phase 2.3（builtin削除）の発展形
|
||||||
- **80k→20k削減**: 大幅なアーキテクチャ簡素化による寄与
|
- **80k→20k削減**: 大幅なアーキテクチャ簡素化による寄与
|
||||||
- **Everything is Plugin完全実現**: VM/LLVM統一設計の完成
|
- **Everything is Plugin完全実現**: VM/LLVM統一設計の完成
|
||||||
|
|||||||
@ -29,4 +29,4 @@ tools/run_vm_stats.sh local_tests/vm_stats_http_500.nyash vm_stats_500.json
|
|||||||
|
|
||||||
関連ドキュメント
|
関連ドキュメント
|
||||||
- `docs/reference/architecture/mir-to-vm-mapping.md`（Result/Handleの取り扱い）
|
- `docs/reference/architecture/mir-to-vm-mapping.md`（Result/Handleの取り扱い）
|
||||||
- `docs/VM_README.md`（VM統計・既知の制約）
|
- `docs/reference/architecture/vm.md`（VM統計・既知の制約）
|
||||||
|
|||||||
@ -35,4 +35,4 @@
|
|||||||
|
|
||||||
関連
|
関連
|
||||||
- CI: `.github/workflows/smoke.yml`（JSON/JUnit 出力は v2 ランナーで取得可能）
|
- CI: `.github/workflows/smoke.yml`（JSON/JUnit 出力は v2 ランナーで取得可能）
|
||||||
- マージ運用: `docs/CONTRIBUTING-MERGE.md`
|
- マージ運用: `docs/development/engineering/merge-strategy.md`
|
||||||
|
|||||||
@ -1,82 +1,5 @@
|
|||||||
# Nyash Refactor Roadmap (Pre–Self-Hosting)
|
# Moved: Refactor Roadmap
|
||||||
|
|
||||||
This document lists large modules, proposes safe splits/commonization, and outlines the MIR13 cleanup plan.
|
このドキュメントは移動しました。
|
||||||
|
- 新しい場所: [development/refactoring/refactor-roadmap.md](development/refactoring/refactor-roadmap.md)
|
||||||
## Large Modules to Split
|
|
||||||
|
|
||||||
Targets are chosen by size and cohesion. Splits are incremental and build-preserving; move code in small steps and re-export in `mod.rs`.
|
|
||||||
|
|
||||||
- `src/mir/verification.rs` (~965 loc)
|
|
||||||
- Split into: `mir/verification/{mod.rs,basic.rs,types.rs,control_flow.rs,ownership.rs}`.
|
|
||||||
- First move leaf helpers and pass-specific checks; keep public API and `pub use` to avoid churn.
|
|
||||||
|
|
||||||
- `src/mir/builder.rs` (~930 loc)
|
|
||||||
- Split into: `mir/builder/{mod.rs,exprs.rs,stmts.rs,decls.rs,control_flow.rs}`.
|
|
||||||
- Extract expression/statement builders first. Keep tests (if any) colocated.
|
|
||||||
|
|
||||||
- `src/mir/instruction.rs` (~896 loc)
|
|
||||||
- Near-term: introduce `mir/instruction/{mod.rs,core.rs,ops.rs,calls.rs}` without changing the enum surface.
|
|
||||||
- Medium-term: migrate to MIR13 (see below) and delete legacy variants.
|
|
||||||
|
|
||||||
- `src/mir/optimizer.rs` (~875 loc)
|
|
||||||
- Split passes into: `mir/optimizer/{mod.rs,constant_folding.rs,dead_code.rs,inline.rs,type_inference.rs}`.
|
|
||||||
- Keep a simple pass runner that sequences the modules.
|
|
||||||
|
|
||||||
- `src/runner/mod.rs` (~885 loc)
|
|
||||||
- Extract modes into `runner/modes/{vm.rs,jit.rs,mir_interpreter.rs,llvm.rs}` if not already, and move glue to `runner/lib.rs`.
|
|
||||||
- Centralize CLI arg parsing in a dedicated module.
|
|
||||||
|
|
||||||
- `src/backend/vm_instructions/boxcall.rs` (~881 loc)
|
|
||||||
- Group by box domain: `boxcall/{array.rs,map.rs,ref.rs,weak.rs,plugin.rs,core.rs}`.
|
|
||||||
- Long-term: most of these become `BoxCall` handlers driven by method ID tables.
|
|
||||||
|
|
||||||
## MIR13 Cleanup Plan
|
|
||||||
|
|
||||||
A large portion of pre-MIR13 variants remain. Current occurrences:
|
|
||||||
|
|
||||||
- ArrayGet: 11, ArraySet: 11
|
|
||||||
- RefNew: 8, RefGet: 15, RefSet: 17
|
|
||||||
- TypeCheck: 13, Cast: 13
|
|
||||||
- PluginInvoke: 14, Copy: 13, Debug: 8, Print: 10, Nop: 9, Throw: 12, Catch: 13, Safepoint: 14
|
|
||||||
|
|
||||||
Phased migration (mechanical, testable per phase):
|
|
||||||
|
|
||||||
1) Introduce shims
|
|
||||||
- Add `BoxCall` helpers covering array/ref/weak/map ops and plugin methods.
|
|
||||||
- Add `TypeOp::{Check,Cast}` modes to map legacy `TypeCheck/Cast`.
|
|
||||||
|
|
||||||
2) Replace uses (non-semantic changes)
|
|
||||||
- Replace within: `backend/dispatch.rs`, `backend/mir_interpreter.rs`, `backend/cranelift/*`, `backend/wasm/codegen.rs`, `mir/printer.rs`, tests.
|
|
||||||
- Keep legacy variants in enum but mark Deprecated for a short period.
|
|
||||||
|
|
||||||
3) Tighten verification/optimizer
|
|
||||||
- Update `verification.rs` to reason about `BoxCall/TypeOp` only.
|
|
||||||
- Update optimizer patterns (e.g., fold Copy → Load/Store; drop Nop/Safepoint occurrences).
|
|
||||||
|
|
||||||
4) Delete legacy variants
|
|
||||||
- Remove `ArrayGet/Set, RefNew/Get/Set, PluginInvoke, TypeCheck, Cast, Copy, Debug, Print, Nop, Throw, Catch, Safepoint`.
|
|
||||||
- Update discriminant printer and state dumps accordingly.
|
|
||||||
|
|
||||||
Use `tools/mir13-migration-helper.sh` to generate per-file tasks and verify.
|
|
||||||
|
|
||||||
## Commonization Opportunities
|
|
||||||
|
|
||||||
- Backend dispatch duplication
|
|
||||||
- `backend/dispatch.rs`, `backend/vm.rs`, and Cranelift JIT lowerings handle overlapping instruction sets. Centralize instruction semantics interfaces (traits) and keep backend-specific execution and codegen in adapters.
|
|
||||||
|
|
||||||
- Method ID resolution
|
|
||||||
- `runtime/plugin_loader_v2` and backend call sites both compute/lookup method IDs. Provide a single resolver module with caching shared by VM/JIT/LLVM.
|
|
||||||
|
|
||||||
- CLI/runtime bootstrap
|
|
||||||
- Move repeated plugin host init/logging messages into a small `runtime/bootstrap.rs` with a single `init_plugins(&Config)` entry point used by all modes.
|
|
||||||
|
|
||||||
## Suggested Order of Work
|
|
||||||
|
|
||||||
1. Split `mir/verification` and `mir/builder` into submodules (no behavior changes).
|
|
||||||
2. Add `BoxCall` shims and `TypeOp` modes; replace printer/dispatch/codegen uses.
|
|
||||||
3. Update verification/optimizer for the unified ops.
|
|
||||||
4. Delete legacy variants and clean up dead code.
|
|
||||||
5. Tackle `runner/mod.rs` and `backend/vm_instructions/boxcall.rs` splits.
|
|
||||||
|
|
||||||
Each step should compile independently and run `tools/smoke_vm_jit.sh` to validate VM/JIT basics.
|
|
||||||
|
|
||||||
|
|||||||
@ -47,7 +47,7 @@
|
|||||||
- パフォーマンス目標（33倍高速化）
|
- パフォーマンス目標（33倍高速化）
|
||||||
- 互換性維持戦略
|
- 互換性維持戦略
|
||||||
|
|
||||||
#### [PLUGIN_ABI.md](../../../PLUGIN_ABI.md)
|
#### [PLUGIN_ABI.md](PLUGIN_ABI.md)
|
||||||
**プラグインABI概要**
|
**プラグインABI概要**
|
||||||
- 現在のTLVベース実装
|
- 現在のTLVベース実装
|
||||||
- プラグイン開発ガイド
|
- プラグイン開発ガイド
|
||||||
@ -131,4 +131,4 @@ if actual_size >= expected_size {
|
|||||||
- [Box設計哲学](../../development/architecture/box-externcall-design.md) - Box/ExternCall境界
|
- [Box設計哲学](../../development/architecture/box-externcall-design.md) - Box/ExternCall境界
|
||||||
|
|
||||||
---
|
---
|
||||||
最終更新: 2025-09-12
|
最終更新: 2025-09-12
|
||||||
|
|||||||
23
docs/reference/abi/PLUGIN_ABI.md
Normal file
23
docs/reference/abi/PLUGIN_ABI.md
Normal file
@ -0,0 +1,23 @@
|
|||||||
|
# Plugin ABI (by-id / tagged) — Snapshot
|
||||||
|
|
||||||
|
This summarizes the ABI surfaces used by LLVM in Phase 15. Details live in NyRT (`crates/nyrt`).
|
||||||
|
|
||||||
|
## Fixed-arity by-id shims
|
||||||
|
- Integer-dominant: `i64 @nyash_plugin_invoke3_i64(i64 type_id, i64 method_id, i64 argc, i64 recv_h, i64 a1, i64 a2, i64 a3, i64 a4)`
|
||||||
|
- Float-dominant: `f64 @nyash_plugin_invoke3_f64(i64 type_id, i64 method_id, i64 argc, i64 recv_h, f64 a1, f64 a2, f64 a3, f64 a4)`
|
||||||
|
|
||||||
|
## Tagged shims (mixed types)
|
||||||
|
- Fixed (<=4 args): `i64 @nyash_plugin_invoke3_tagged_i64(i64 type_id, i64 method_id, i64 argc, i64 recv_h, i64 a1, i64 t1, i64 a2, i64 t2, i64 a3, i64 t3, i64 a4, i64 t4)`
|
||||||
|
- Vector (N args): `i64 @nyash.plugin.invoke_tagged_v_i64(i64 type_id, i64 method_id, i64 argc, i64 recv_h, i8* vals, i8* tags)`
|
||||||
|
|
||||||
|
Tag codes (minimal):
|
||||||
|
- 3=int, 5=float, 8=handle(ptr). Others are reserved/experimental.
|
||||||
|
|
||||||
|
## Return mapping (LLVM lowering)
|
||||||
|
- If destination is annotated as Integer/Bool → keep i64 as integer.
|
||||||
|
- If destination is String/Box/Array/Future/Unknown → cast i64 handle to opaque pointer for SSA flow; do not `inttoptr` where a C string is expected.
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
- These ABIs are used by both built-ins (nyrt) and plugins for consistency.
|
||||||
|
- The LLVM backend is the reference; other backends will be aligned later.
|
||||||
|
|
||||||
@ -6,7 +6,7 @@ This index points to the currently maintained architectural documents:
|
|||||||
- Execution Backends: reference/architecture/execution-backends.md
|
- Execution Backends: reference/architecture/execution-backends.md
|
||||||
- Lowering Contexts: ../../design/LOWERING_CONTEXTS.md
|
- Lowering Contexts: ../../design/LOWERING_CONTEXTS.md
|
||||||
- LLVM Layer Overview: ../../design/LLVM_LAYER_OVERVIEW.md
|
- LLVM Layer Overview: ../../design/LLVM_LAYER_OVERVIEW.md
|
||||||
- VM Overview: VM_README.md
|
- VM Overview: vm.md
|
||||||
- Cranelift AOT design: ../../design/backend-cranelift-aot-design.md
|
- Cranelift AOT design: ../../design/backend-cranelift-aot-design.md
|
||||||
|
|
||||||
Note: Some long-form papers reside under `private/papers/reference/architecture/`.
|
Note: Some long-form papers reside under `private/papers/reference/architecture/`.
|
||||||
|
|||||||
@ -115,4 +115,4 @@ Nyash Source ──▶ MIR (Builder)
|
|||||||
|
|
||||||
See also
|
See also
|
||||||
- `docs/guides/examples/http_result_patterns.md` - HTTPのResult挙動（unreachable/404/500）のE2E例
|
- `docs/guides/examples/http_result_patterns.md` - HTTPのResult挙動（unreachable/404/500）のE2E例
|
||||||
- `docs/VM_README.md` - VM統計とプラグイン周りの既知制約
|
- `docs/reference/architecture/vm.md` - VM統計とプラグイン周りの既知制約
|
||||||
|
|||||||
@ -5,4 +5,4 @@ For the full guide, see:
|
|||||||
|
|
||||||
Additional references:
|
Additional references:
|
||||||
- ../../design/backend-llvm-implementation-guide.md
|
- ../../design/backend-llvm-implementation-guide.md
|
||||||
- VM_README.md
|
- vm.md
|
||||||
|
|||||||
70
docs/reference/architecture/llvm-harness.md
Normal file
70
docs/reference/architecture/llvm-harness.md
Normal file
@ -0,0 +1,70 @@
|
|||||||
|
# llvmlite Harness（正式導入・Rust LLVM 対置運用）
|
||||||
|
|
||||||
|
Purpose
|
||||||
|
- Python + llvmlite による高速・柔軟な LLVM 生成経路を提供（検証・プロトタイプと将来の主役）。
|
||||||
|
- Rust/inkwell 経路と並走し、代表ケースで機能同値（戻り値・検証）を維持。
|
||||||
|
|
||||||
|
Switch
|
||||||
|
- `NYASH_LLVM_USE_HARNESS=1` でハーネス優先（LLVM バックエンド入口から起動）。
|
||||||
|
|
||||||
|
Tracing
|
||||||
|
- `NYASH_LLVM_TRACE_FINAL=1` を設定すると、代表コール（`Main.node_json/3`, `Main.esc_json/1`, `main` 等）を標準出力へ簡易トレースします。
|
||||||
|
ON/OFF の最終 JSON 突合の補助に使用してください。
|
||||||
|
|
||||||
|
Protocol
|
||||||
|
- Input: MIR14 JSON（Rust 前段で Resolver/LoopForm 規約を満たした形）。
|
||||||
|
- Output: `.o` オブジェクト（既定: `NYASH_AOT_OBJECT_OUT` または `NYASH_LLVM_OBJ_OUT`）。
|
||||||
|
- 入口: `ny_main() -> i64`（戻り値は exit code 相当。必要時 handle 正規化を行う）。
|
||||||
|
|
||||||
|
CLI（crate）
|
||||||
|
- `crates/nyash-llvm-compiler` 提供の `ny-llvmc` は llvmlite ハーネスの薄ラッパーだよ。
|
||||||
|
- ダミー: `./target/release/ny-llvmc --dummy --out /tmp/dummy.o`
|
||||||
|
- JSON→.o: `./target/release/ny-llvmc --in mir.json --out out.o`
|
||||||
|
- JSON→EXE（新規）: `./target/release/ny-llvmc --in mir.json --emit exe --nyrt target/release --out app`
|
||||||
|
- `--nyrt <dir>` で `libnyrt.a` の位置を指定（省略時は `target/release`→`crates/nyrt/target/release` の順に探索）
|
||||||
|
- 追加フラグは `--libs "<flags>"` で渡せる（例: `--libs "-static"`）
|
||||||
|
- 既定のハーネススクリプトは `tools/llvmlite_harness.py`（`--harness` で上書き可）。
|
||||||
|
|
||||||
|
Quick Start
|
||||||
|
- 依存: `python3 -m pip install llvmlite`
|
||||||
|
- ダミー生成（配線検証）:
|
||||||
|
- `python3 tools/llvmlite_harness.py --out /tmp/dummy.o`
|
||||||
|
- NyRT（libnyrt.a）とリンクして EXE 化（例: `cc /tmp/dummy.o -L target/release -Wl,--whole-archive -lnyrt -Wl,--no-whole-archive -lpthread -ldl -lm -o app_dummy`）。
|
||||||
|
|
||||||
|
Wiring（Rust 側）
|
||||||
|
- `NYASH_LLVM_USE_HARNESS=1` のとき:
|
||||||
|
1) `--emit-mir-json <path>` 等で MIR(JSON) を出力
|
||||||
|
2) `python3 tools/llvmlite_harness.py --in <mir.json> --out <obj.o>` を起動
|
||||||
|
3) 成功後は通常のリンク手順（NyRT とリンク）
|
||||||
|
|
||||||
|
Tools / CLI（統合フロー）
|
||||||
|
- crate 直結の EXE 出力: `NYASH_LLVM_COMPILER=crate NYASH_LLVM_EMIT=exe tools/build_llvm.sh apps/tests/ternary_basic.nyash -o app`
|
||||||
|
- 環境変数 `NYASH_LLVM_NYRT` で NyRT の場所を、`NYASH_LLVM_LIBS` で追加フラグを指定できる。
|
||||||
|
- CLI から直接 EXE 出力（新規）:
|
||||||
|
- `./target/release/nyash --emit-exe tmp/app --backend mir apps/tests/ternary_basic.nyash`
|
||||||
|
- 追加オプション: `--emit-exe-nyrt <dir>` / `--emit-exe-libs "<flags>"`
|
||||||
|
|
||||||
|
Scope（Phase 15）
|
||||||
|
- 最小命令: Const/BinOp/Compare/Branch/Jump/Return（PHI は LLVM 側で合成）
|
||||||
|
- 文字列: NyRT Shim（`nyash.string.len_h`, `charCodeAt_h`, `concat_hh`, `eq_hh`）を declare → call
|
||||||
|
- NewBox/ExternCall/BoxCall: まずは固定シンボル／by-id を優先（段階導入）
|
||||||
|
- 目標: `apps/selfhost/tools/dep_tree_min_string.nyash` の `.ll verify green → .o` 安定化
|
||||||
|
|
||||||
|
Acceptance
|
||||||
|
- Harness ON/OFF で機能同値（戻り値/検証）。代表ケースで `.ll verify green` と `.o` 生成成功。
|
||||||
|
|
||||||
|
Notes
|
||||||
|
- 初版は固定 `ny_main` から開始してもよい（配線確認）。以降、MIR 命令を順次対応。
|
||||||
|
- ハーネスは自律（外部状態に依存しない）。エラーは即 stderr に詳細を出す。
|
||||||
|
|
||||||
|
PHI Policy（要点）
|
||||||
|
- Phase‑15 の既定は PHI‑on。MIR 側で SSA `Phi` を生成し、ハーネスは incoming の検証と最終 IR への反映だけを行う。
|
||||||
|
- レガシー互換のために PHI‑off が必要なケースでは `NYASH_MIR_NO_PHI=1` を明示してね（ハーネスは旧 edge-copy 互換ルートで補完する）。
|
||||||
|
- 詳細と背景は `docs/reference/mir/phi_policy.md` を参照。
|
||||||
|
|
||||||
|
Schema Validation（任意）
|
||||||
|
- JSON v0 のスキーマは `docs/reference/mir/json_v0.schema.json` にあるよ。
|
||||||
|
- 検証: `python3 tools/validate_mir_json.py <mir.json>`（要: `python3 -m pip install jsonschema`）。
|
||||||
|
|
||||||
|
Appendix: 静的リンクについて
|
||||||
|
- 生成 EXE は NyRT（libnyrt.a）を静的リンク。完全静的（-static）は musl 推奨（dlopen 不可になるため動的プラグインは使用不可）。
|
||||||
107
docs/reference/architecture/vm.md
Normal file
107
docs/reference/architecture/vm.md
Normal file
@ -0,0 +1,107 @@
|
|||||||
|
# Nyash VM 実行基盤ガイド（更新）
|
||||||
|
|
||||||
|
- プラグインBox引数の最小対応を追加（TLV: BoxRef）
|
||||||
|
- TLVタグ: 1=Bool, 2=I32, 3=I64, 4=F32, 5=F64, 6=String, 7=Bytes, 8=Handle(BoxRef)
|
||||||
|
- BoxRefはプラグインBox参照（type_id:u32, instance_id:u32）を8バイトでエンコード
|
||||||
|
- ユーザー定義/複雑なBoxは当面一部非対応（toStringフォールバック）。標準Boxはプラグイン経由で統一
|
||||||
|
|
||||||
|
現状のルーティング（Plugin-First）:
|
||||||
|
- User-defined: MIR関数（{Box}.{method}/{N}) にCall化（関数存在時）。それ以外はBoxCall。
|
||||||
|
- Plugin: BoxCall → PluginInvoke（method_idが解決可能）→ それ以外は名前解決で PluginHost.invoke_instance_method。
|
||||||
|
|
||||||
|
今後のタスク:
|
||||||
|
- VM側のfrom Parent.method対応（Builder/VM両対応）
|
||||||
|
- TLVの型拡張（Float/配列/BoxRef戻り値など）
|
||||||
|
|
||||||
|
## 🧮 VM実行統計（NYASH_VM_STATS / JSON）
|
||||||
|
|
||||||
|
VMは命令カウントと実行時間を出力できます。
|
||||||
|
|
||||||
|
使い方（CLIフラグ）:
|
||||||
|
```bash
|
||||||
|
# 人間向け表示
|
||||||
|
nyash --backend vm --vm-stats program.nyash
|
||||||
|
|
||||||
|
# JSON出力
|
||||||
|
nyash --backend vm --vm-stats --vm-stats-json program.nyash
|
||||||
|
```
|
||||||
|
|
||||||
|
環境変数（直接指定）:
|
||||||
|
```bash
|
||||||
|
NYASH_VM_STATS=1 ./target/debug/nyash --backend vm program.nyash
|
||||||
|
NYASH_VM_STATS=1 NYASH_VM_STATS_JSON=1 ./target/debug/nyash --backend vm program.nyash
|
||||||
|
# 代替: NYASH_VM_STATS_FORMAT=json
|
||||||
|
```
|
||||||
|
|
||||||
|
出力は `total`（総命令数）, `elapsed_ms`（経過時間）, `counts`（命令種別→回数）, `top20`（上位20種）を含みます。
|
||||||
|
|
||||||
|
## 既知の制約とTips（VM×プラグイン）
|
||||||
|
- Netプラグイン（HTTP）
|
||||||
|
- unreachable（接続不可/タイムアウト）は `Result.Err(ErrorBox)`。
|
||||||
|
- HTTP 404/500 は `Result.Ok(Response)`（アプリ側で `response.status` を確認）。
|
||||||
|
- デバッグ: `NYASH_NET_LOG=1 NYASH_NET_LOG_FILE=net_plugin.log`。
|
||||||
|
- FileBox
|
||||||
|
- `close()` は `Ok(Void)`。`match Ok(_)` で受けるか、戻り値を無視してよい。
|
||||||
|
- Handle（BoxRef）戻り
|
||||||
|
- TLV tag=8（type_id:u32, instance_id:u32）。Loaderが返り値typeに対応する `fini_method_id` を設定し `PluginBoxV2` を構築。
|
||||||
|
- `scope_tracker` がスコープ終了時に `fini()` を呼ぶ（メモリ安全）。
|
||||||
|
- 大きいボディ/多ヘッダー/タイムアウト
|
||||||
|
- 逐次拡張中。異常時の挙動は上記Result規約に従う。実行ログと `--vm-stats` を併用して診断。
|
||||||
|
- 反復タイムアウト: `local_tests/socket_repeated_timeouts.nyash` で `acceptTimeout/recvTimeout` の連続ケース確認
|
||||||
|
- BoxCallデバッグ: `NYASH_VM_DEBUG_BOXCALL=1` でBoxCallの受け手型・引数型・処理経路（enter/fastpath/unified）・結果型をstderr出力
|
||||||
|
- 例: `NYASH_VM_DEBUG_BOXCALL=1 ./target/release/nyash --backend vm local_tests/test_vm_array_getset.nyash`
|
||||||
|
|
||||||
|
## 🔧 BoxCallの統一経路（Phase 9.79b）
|
||||||
|
|
||||||
|
### method_id（スロット）によるBoxCall
|
||||||
|
- Builderが受け手型を推論できる場合、`BoxCall`に数値`method_id`（スロット）を付与。
|
||||||
|
- 低スロットはユニバーサル予約（0=toString, 1=type, 2=equals, 3=clone）。
|
||||||
|
- ユーザー定義Boxは宣言時にインスタンスメソッドへスロットを4番から順に予約（決定論的）。
|
||||||
|
|
||||||
|
### VMの実行経路（thunk + PIC）
|
||||||
|
- ユニバーサルスロット（0..3）はVMのfast-path thunkで即時処理。
|
||||||
|
- toString/type/equals/cloneの4種は受け手`VMValue`から直接評価。
|
||||||
|
- それ以外は以下の順で処理:
|
||||||
|
1. Mono-PIC（モノモーフィックPIC）直呼び: 受け手型×method（またはmethod_id）のキーでホットサイトを判定し、
|
||||||
|
`InstanceBox`は関数名キャッシュを使って `{Class}.{method}/{arity}` を直接呼び出す（閾値=8）。
|
||||||
|
2. 既存経路: `InstanceBox`はMIR関数へCall、それ以外は各Boxのメソッドディスパッチへフォールバック。
|
||||||
|
|
||||||
|
環境変数（デバッグ）:
|
||||||
|
```bash
|
||||||
|
NYASH_VM_DEBUG_BOXCALL=1 # BoxCallの入出力と処理経路を出力
|
||||||
|
NYASH_VM_PIC_DEBUG=1 # PICヒットのしきい値通過時にログ
|
||||||
|
```
|
||||||
|
|
||||||
|
今後の拡張:
|
||||||
|
- 一般`method_id`（ユーザー/プラグイン）に対するvtableスロット→thunk直呼び。
|
||||||
|
- PICのキャッシュ無効化（型version）と多相PICへの拡張（Phase 10）。
|
||||||
|
- SocketBox（VM）
|
||||||
|
- 基本API: `bind/listen/accept/connect/read/write/close/isServer/isConnected`
|
||||||
|
- タイムアウト: `acceptTimeout(ms)` は接続なしで `void`、`recvTimeout(ms)` は空文字を返す
|
||||||
|
- 簡易E2E: `local_tests/socket_timeout_server.nyash` と `socket_timeout_client.nyash`
|
||||||
|
- Void 比較の扱い（VM）
|
||||||
|
- `Void` は値を持たないため、`Eq/Ne` のみ有効。`Void == Void` は真、それ以外の型との `==` は偽（`!=` は真）。
|
||||||
|
- 順序比較（`<, <=, >, >=`）は `TypeError`。
|
||||||
|
|
||||||
|
## E2E 実行例（HTTPのResult挙動）
|
||||||
|
|
||||||
|
代表ケースを `tools/run_vm_stats.sh` で実行できます。`--vm-stats-json` により命令プロファイルも取得可能です。
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 別ターミナルでサーバ起動
|
||||||
|
./target/release/nyash local_tests/http_server_statuses.nyash
|
||||||
|
|
||||||
|
# クライアント（別ターミナル）
|
||||||
|
tools/run_vm_stats.sh local_tests/vm_stats_http_ok.nyash vm_stats_ok.json
|
||||||
|
tools/run_vm_stats.sh local_tests/vm_stats_http_404.nyash vm_stats_404.json
|
||||||
|
tools/run_vm_stats.sh local_tests/vm_stats_http_500.nyash vm_stats_500.json
|
||||||
|
|
||||||
|
# 到達不能（サーバ不要）
|
||||||
|
tools/run_vm_stats.sh local_tests/vm_stats_http_err.nyash vm_stats_err.json
|
||||||
|
```
|
||||||
|
|
||||||
|
期待されるResultモデル
|
||||||
|
- unreachable（接続不可/タイムアウト）: `Result.Err(ErrorBox)`
|
||||||
|
- 404/500 等のHTTPエラー: `Result.Ok(Response)`（アプリ側で `response.status` を評価）
|
||||||
|
|
||||||
|
詳細: `docs/reference/architecture/mir-to-vm-mapping.md` と `docs/guides/examples/http_result_patterns.md` を参照。
|
||||||
25
docs/reference/plugin-system/externcall.md
Normal file
25
docs/reference/plugin-system/externcall.md
Normal file
@ -0,0 +1,25 @@
|
|||||||
|
# ExternCall Policy (Phase 15)
|
||||||
|
|
||||||
|
## Allowed Interfaces (minimal set)
|
||||||
|
- `env.console.{log,warn,error,readLine}`
|
||||||
|
- `env.debug.trace`
|
||||||
|
- `env.system.{exit,now}` (if present)
|
||||||
|
|
||||||
|
All other host interactions should go through BoxCall (NyRT or plugins).
|
||||||
|
|
||||||
|
## Argument‑type‑based selection
|
||||||
|
- For `env.console.{log,warn,error}` and `env.debug.trace`:
|
||||||
|
- If the single argument is `i8*` (C string), call the C‑string variant:
|
||||||
|
- `nyash.console.log(i8*)`, `nyash.console.warn(i8*)`, `nyash.console.error(i8*)`
|
||||||
|
- `nyash.debug.trace(i8*)`
|
||||||
|
- Otherwise convert to `i64` and call the handle variant:
|
||||||
|
- `nyash.console.log_handle(i64)`, `nyash.console.warn_handle(i64)`, `nyash.console.error_handle(i64)`
|
||||||
|
- `nyash.debug.trace_handle(i64)`
|
||||||
|
|
||||||
|
## Rationale
|
||||||
|
- Keeps the AOT string path fast and avoids accidental `inttoptr` of handles.
|
||||||
|
- Avoids adding broad implicit conversions in ExternCall; selection is local and explicit.
|
||||||
|
|
||||||
|
## Non‑LLVM Backends
|
||||||
|
- VM, Cranelift JIT/AOT, and the interpreter may not implement this policy yet (not MIR14‑ready). LLVM is authoritative; other backends will align after stabilization.
|
||||||
|
|
||||||
@ -19,6 +19,12 @@ static box Main {
|
|||||||
samples.push("true")
|
samples.push("true")
|
||||||
samples.push("false")
|
samples.push("false")
|
||||||
samples.push("42")
|
samples.push("42")
|
||||||
|
samples.push("-0")
|
||||||
|
samples.push("0")
|
||||||
|
samples.push("3.14")
|
||||||
|
samples.push("-2.5")
|
||||||
|
samples.push("6.02e23")
|
||||||
|
samples.push("-1e-9")
|
||||||
samples.push("\"hello\"")
|
samples.push("\"hello\"")
|
||||||
samples.push("[]")
|
samples.push("[]")
|
||||||
samples.push("{}")
|
samples.push("{}")
|
||||||
@ -46,6 +52,12 @@ false
|
|||||||
[]
|
[]
|
||||||
{}
|
{}
|
||||||
{"a":1}
|
{"a":1}
|
||||||
|
0
|
||||||
|
0
|
||||||
|
3.14
|
||||||
|
-2.5
|
||||||
|
6.02e23
|
||||||
|
-1e-9
|
||||||
TXT
|
TXT
|
||||||
)
|
)
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user