tomoaki/hakorune
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
adc10fdf54086060d2f5c0028e32ba4511c25278
hakorune/docs/reference/environment-variables.md
nyash-codex adc10fdf54 Phase 123 proper完了：hako_check JoinIR実装（環境変数選択可能化） 
## 実装内容

### 1. 環境変数フラグ追加
- NYASH_HAKO_CHECK_JOINIR でJoinIR/Legacy経路を切り替え可能
- src/config/env/hako_check.rs で hako_check_joinir_enabled() 実装
- デフォルト: false（レガシー経路）で後方互換性確保

### 2. MIR Builder JoinIR スイッチ
- cf_if() メソッドにフラグチェック追加
- try_cf_if_joinir() プレースホルダー実装（Phase 124で完全実装）
- JoinIR → legacy フォールバック機構を構築

### 3. テストケース作成（4個）
- phase123_simple_if.hako
- phase123_nested_if.hako
- phase123_while_loop.hako
- phase123_if_in_loop.hako

### 4. テスト結果
✅ Legacy path: 4/4 PASS
✅ JoinIR path: 4/4 PASS
（JoinIR path は現在フォールバック経由で動作）

### 5. ドキュメント更新
- environment-variables.md: NYASH_HAKO_CHECK_JOINIR 記載
- phase121_hako_check_joinir_design.md: Phase 123実装セクション追加
- hako_check_design.md: 2パス実行フロー図を追加
- CURRENT_TASK.md: Phase 123完了を記録

## 数値成果

- 新規ファイル: 2個 (config/env/hako_check.rs, test cases × 4, test script)
- 修正ファイル: 6個
- 総追加行数: 335行
- ビルド: Zero errors

## 設計・実装の特徴

✅ Environment variable で簡単に経路切り替え可能
✅ レガシー経路を完全に保持（後方互換性）
✅ JoinIR基盤を Phase 124 での完全実装に向けて構築
✅ フォールバック機構でリスク最小化

## 次のステップ

Phase 124: JoinIR 完全実装＆デフォルト化
- try_cf_if_joinir() を IfSelectLowerer と統合
- Loop JoinIR 統合追加
- JoinIR をデフォルト経路に変更
- NYASH_LEGACY_PHI=1 で legacy フォールバック可能に

🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-04 06:17:10 +09:00

217 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 環境変数リファレンス
Nyash の主要な環境変数をカテゴリ別に整理するよ。`適用経路` はどのパスで効くかを示す:
- Rust AST: Rust パーサ直通 (`--dump-mir` など)
- JSON v0/Stage-1: selfhost/Stage-1/`--ny-parser-pipe` 経由（json_v0_bridge で処理）
- Any: どの経路でも有効
---
## ダンプ / 診断
| 変数 | デフォルト | 適用経路 | 説明 |
| --- | --- | --- | --- |
| `RUST_MIR_DUMP_PATH=/tmp/out.mir` | OFF | JSON v0/Stage-1 | MIR printer の出力をファイルに書く (`json_v0_bridge::maybe_dump_mir` 経由) |
| `NYASH_CLI_VERBOSE=1` | OFF | Any | 詳細ログ。`maybe_dump_mir` が stdout に MIR を出す |
| `NYASH_CLI_VERBOSE=2` | OFF | Any | さらに詳細なログ（Ny compiler 経路の診断ログ含む） |
| `NYASH_VM_DUMP_MIR=1` | OFF | Any | VM 実行前の MIR を出力 |
| `NYASH_DUMP_JSON_IR=1` | OFF | Any | JSON IR をダンプ |
| `NYASH_DEBUG_STACK_OVERFLOW=1` | OFF | Any | スタックオーバーフロー時に backtrace を有効化 |
### ダンプの使い分け
- Rust AST 直通: `./target/release/hakorune --dump-mir apps/tests/minimal.hako`（env は不要、stdout のみ）
- JSON v0 経路/Stage-1: `RUST_MIR_DUMP_PATH=/tmp/out.mir NYASH_USE_STAGE1_CLI=1 STAGE1_EMIT_MIR_JSON=1 ./target/release/hakorune --dump-mir`（stdout + ファイル）
---
## Stage-1 / selfhost CLI
| 変数 | デフォルト | 適用経路 | 説明 |
| --- | --- | --- | --- |
| `NYASH_USE_STAGE1_CLI=1` | OFF | Stage-1 | Stage-1 stub 経由に切替 |
| `NYASH_STAGE1_MODE=emit-mir` | unset | Stage-1 | `emit-program` / `emit-mir` / `run` を明示 |
| `STAGE1_EMIT_PROGRAM_JSON=1` | OFF | Stage-1 | Program(JSON v0) を吐いて終了（レガシー alias） |
| `STAGE1_EMIT_MIR_JSON=1` | OFF | Stage-1 | Program(JSON v0)→MIR(JSON) を Rust 側で降ろす（レガシー alias） |
| `HAKO_STAGE1_MODE={emit-program\|emit-mir\|run}` | unset | Stage-1 | .hako / Stage-1 ルート専用のモード指定（`--hako-*` が設定） |
| `HAKO_EMIT_PROGRAM_JSON=1` | OFF | Stage-1 | `.hako` stub に Program(JSON v0) emit を指示 |
| `HAKO_EMIT_MIR_JSON=1` | OFF | Stage-1 | `.hako` stub に MIR(JSON) emit を指示（json_v0_bridge 経由） |
| `NYASH_STAGE1_INPUT=path` | unset | Stage-1 | 入力ソース（alias: `STAGE1_SOURCE`, `STAGE1_INPUT`） |
| `HAKO_STAGE1_INPUT=path` | unset | Stage-1 | `.hako` stub 用の入力ソース（`--hako-*` が設定） |
| `NYASH_STAGE1_PROGRAM_JSON=path` | unset | Stage-1 | Program(JSON v0) のパス（alias: `STAGE1_PROGRAM_JSON`） |
| `HAKO_STAGE1_PROGRAM_JSON=path` | unset | Stage-1 | `.hako` stub 用 Program(JSON v0) パス |
| `NYASH_STAGE1_BACKEND=vm` | `vm` | Stage-1 | Stage-1 実行の backend ヒント（alias: `STAGE1_BACKEND`） |
| `NYASH_STAGE1_CLI_CHILD=1` | OFF | Stage-1 | 再帰呼び出しガード |
| `STAGE1_CLI_ENTRY=...` | `lang/src/runner/stage1_cli.hako` | Stage-1 | Stage-1 stub のエントリ差し替え |
| `STAGE1_*` alias | legacy | Stage-1 | `NYASH_STAGE1_*` の旧名。互換のため受理するが順次廃止予定 |
### Stage-1 経路の例
```bash
# Stage-1 で MIR(JSON) を受け取り、Rust 側で dump
RUST_MIR_DUMP_PATH=/tmp/out.mir \
NYASH_USE_STAGE1_CLI=1 STAGE1_EMIT_MIR_JSON=1 \
./target/release/hakorune --dump-mir apps/tests/minimal.hako
# hako- 前置で Stage-1 stub 経由
./target/release/hakorune --hako-emit-program-json /tmp/out.json apps/tests/minimal.hako
./target/release/hakorune --hako-emit-mir-json /tmp/out.mir apps/tests/minimal.hako --dump-mir
```
---
## Parser / using
| 変数 | デフォルト | 適用経路 | 説明 |
| --- | --- | --- | --- |
| `NYASH_FEATURES=stage3` | `stage3` (implicit) | Any | カンマ区切りの機能フラグ。`stage3` で Stage-3 構文を許可（既定ON）。 |
| `NYASH_PARSER_STAGE3=1` | legacy | Any | Stage-3 旧エイリアス。将来削除予定。OFF にしたい場合のみ指定。 |
| `HAKO_PARSER_STAGE3=1` | legacy | Any | `.hako` 向け Stage-3 legacy alias。将来削除予定。 |
| `NYASH_ENABLE_USING=1` | ON | Any | using 文を有効化 |
| `HAKO_ENABLE_USING=1` | ON | Any | using 文 alias (.hako) |
| `NYASH_RESOLVE_TRACE=1` | OFF | Any | using/prelude 解決のトレース |
| `NYASH_VM_DUMP_MERGED_HAKO=1` | OFF | Rust AST | using/prelude マージ後の Hako ソースをダンプ |
---
## Runner / backend 選択
| 変数 | デフォルト | 適用経路 | 説明 |
| --- | --- | --- | --- |
| `NYASH_VM_USE_PY=1` | OFF | Any | PyVM を優先実行 |
| `NYASH_PIPE_USE_PYVM=1` | OFF | JSON v0/Stage-1 | pipe 実行を PyVM に直送 |
| `NYASH_VM_PLUGIN_STRICT=1` | OFF | Any | 必須プラグイン欠如で fail-fast |
| `NYASH_FAIL_FAST=0` | ON | Any | フォールバックを許容（既定は拒否） |
---
## Selfhost compiler / Ny compiler
| 変数 | デフォルト | 適用経路 | 説明 |
| --- | --- | --- | --- |
| `NYASH_USE_NY_COMPILER=1` | OFF | JSON v0 | Ny selfhost コンパイラを使用 |
| `NYASH_NY_COMPILER_STAGE3=1` | OFF | JSON v0 | Ny コンパイラ子プロセスで Stage-3 surface を許可 |
| `NYASH_NY_COMPILER_TIMEOUT_MS=2000` | `2000` | JSON v0 | selfhost 子プロセスのタイムアウト (ms) |
| `NYASH_NY_COMPILER_EMIT_ONLY=1` | ON | JSON v0 | selfhost コンパイラを emit-only で動かす |
| `NYASH_NY_COMPILER_CHILD_ARGS="-- --min-json"` | unset | JSON v0 | 子プロセスへ透過する追加引数 |
### Ny compiler 経路の観測テンプレート (Phase 29)
```bash
# Ny compiler 経路で Program(JSON v0)→MIR→dump を観測
NYASH_USE_NY_COMPILER=1 \
NYASH_FEATURES=stage3 \
RUST_MIR_DUMP_PATH=/tmp/ny_selfhost_minimal.mir \
NYASH_CLI_VERBOSE=2 \
./target/release/hakorune --dump-mir apps/tests/minimal_ssa_skip_ws.hako \
2>/tmp/ny_selfhost_minimal.log
```
確認項目:
- `/tmp/ny_selfhost_minimal.log` に以下の診断ログが出ているか:
- `[selfhost/ny] spawning Ny compiler child process: ...`
- `[selfhost/ny] received Program(JSON v0), size=... bytes`
- `[selfhost/ny] lowering Program(JSON v0) → MIR via json_v0_bridge`
- `[selfhost/ny] calling maybe_dump_mir (RUST_MIR_DUMP_PATH=..., cli_verbose=...)`
- `[selfhost/ny] ✅ MIR dump file created` または `⚠️ MIR dump file NOT created`
注意: Ny selfhost compiler のエントリは現在 `lang/src/compiler/entry/compiler.hako` に統一されているよ。このファイルが存在しない場合、preferred child process 経路は発火しない。
---
## GC / Runtime
| 変数 | デフォルト | 適用経路 | 説明 |
| --- | --- | --- | --- |
| `NYASH_GC_MODE={auto|rc+cycle|minorgen|stw|rc|off}` | `rc+cycle` | Any | GC モード選択 |
| `NYASH_GC_TRACE=1` | OFF | Any | GC トレース出力 (0-3) |
| `NYASH_GC_METRICS=1` | OFF | Any | GC メトリクス (text) |
| `NYASH_GC_METRICS_JSON=1` | OFF | Any | GC メトリクス (JSON) |
| `NYASH_VM_TRACE=1` | OFF | Any | VM 実行トレース |
---
## プラグイン / Box
| 変数 | デフォルト | 適用経路 | 説明 |
| --- | --- | --- | --- |
| `NYASH_DISABLE_PLUGINS=1` | OFF | Any | プラグイン無効化 |
| `NYASH_BOX_FACTORY_POLICY={builtin_first|plugin_first}` | `builtin_first` | Any | Box factory の優先順位 |
| `NYASH_FILEBOX_MODE={auto|plugin|builtin}` | `auto` | Any | FileBox 実装選択 |
---
## JoinIR トグル (Phase 72 整理版)
JoinIR は制御構造を関数呼び出し + 継続に正規化する IR 層。フラグは config/env のポリシーで集約するよ。
**ポリシー入口**
- `joinir_core_enabled()` … `NYASH_JOINIR_CORE` が優先。未設定時は `NYASH_JOINIR_EXPERIMENT` や IfSelect/VM bridge/LLVM 実験の明示設定で自動 ON。
- `joinir_dev_enabled()` … `NYASH_JOINIR_DEV=1` または JoinIR debug level > 0 で ON（開発者向け束ねスイッチ）。
### Core（本線化対象）
| 変数 | デフォルト | 説明 |
| --- | --- | --- |
| `NYASH_JOINIR_CORE` | unset | Core トグルの明示 ON/OFF（未設定時は下記を見て自動判定） |
| `NYASH_JOINIR_EXPERIMENT` | OFF | JoinIR 実験メイントグル（Core 判定に含まれる） |
| `HAKO_JOINIR_IF_SELECT` | OFF | IfSelect/IfMerge JoinIR 経路。エイリアス `NYASH_JOINIR_IF_SELECT` は Deprecated。 |
| `HAKO_JOINIR_IF_IN_LOOP_ENABLE` | OFF | if-in-loop JoinIR 本線切替（Core 候補）。 |
| `NYASH_JOINIR_VM_BRIDGE` | OFF | VM bridge Route B。Core 判定に含まれる。 |
| `NYASH_JOINIR_LLVM_EXPERIMENT` | OFF | LLVM 経路 JoinIR 実験（ハーネス専用）。Core 判定に含まれる。 |
| `NYASH_HAKO_CHECK_JOINIR` | OFF | hako_check で JoinIR 経路を使用（Phase 123+）。Phase 124 で ON がデフォルトに。 |
### DevOnly（開発/計測専用）
| 変数 | デフォルト | 説明 |
| --- | --- | --- |
| `NYASH_JOINIR_DEV` | OFF | DevOnly まとめて ON。 |
| `NYASH_JOINIR_LOWER_FROM_MIR` | OFF | MIR ベース lowering 切替。 |
| `NYASH_JOINIR_LOWER_GENERIC` | OFF | 関数名フィルタなし generic lowering。 |
| `NYASH_JOINIR_VM_BRIDGE_DEBUG` | OFF | VM bridge 追加ログ。 |
| `NYASH_JOINIR_MAINLINE_DEBUG` | OFF | Mainline 追加ログ。 |
| `HAKO_JOINIR_IF_IN_LOOP_DRYRUN` | OFF | if-in-loop dry-run。 |
| `HAKO_JOINIR_IF_TOPLEVEL` / `_DRYRUN` | OFF | ループ外 if JoinIR 経路 / dry-run。 |
| `HAKO_JOINIR_STAGE1` | OFF | Stage‑1 JoinIR 経路。 |
| `HAKO_JOINIR_PRINT_TOKENS_MAIN` | OFF | print_tokens main A/B。 |
| `HAKO_JOINIR_ARRAY_FILTER_MAIN` | OFF | array.filter main A/B。 |
| `NYASH_JOINIR_DEBUG` / `HAKO_JOINIR_DEBUG` | OFF | JoinIR デバッグログ。 |
### Deprecated / 廃止候補
| 変数 | 状態 | 説明 |
| --- | --- | --- |
| `HAKO_JOINIR_NESTED_IF` | Deprecated候補 | Route B nested if。 |
| `HAKO_JOINIR_READ_QUOTED` / `_IFMERGE` | Deprecated候補 | read_quoted JoinIR 実験。 |
### 使用例
```bash
# Core JoinIR + Stage-3（推奨）
env NYASH_FEATURES=stage3 NYASH_JOINIR_CORE=1 ./target/release/hakorune program.hako
# VM bridge Route B（開発用）
env NYASH_FEATURES=stage3 NYASH_JOINIR_EXPERIMENT=1 NYASH_JOINIR_VM_BRIDGE=1 ./target/release/hakorune program.hako
# LLVM ハーネス JoinIR 実験
env NYASH_FEATURES=stage3 NYASH_LLVM_USE_HARNESS=1 \
NYASH_JOINIR_EXPERIMENT=1 NYASH_JOINIR_LLVM_EXPERIMENT=1 \
./target/release/hakorune --backend llvm apps/tests/minimal_ssa_skip_ws.hako
```
詳細: [ENV_INVENTORY.md](../private/roadmap2/phases/phase-29-longterm-joinir-full/ENV_INVENTORY.md) / [Phase 72 フラグ整理](../private/roadmap2/phases/phase-72-joinir-dev-flags/README.md)
---
## MIR 検証系（代表）
| 変数 | デフォルト | 適用経路 | 説明 |
| --- | --- | --- | --- |
| `NYASH_VERIFY_ALLOW_NO_PHI=1` | OFF | Any | PHI 検証をスキップ |
| `NYASH_VERIFY_EDGE_COPY_STRICT=1` | OFF | Any | Edge copy 検証を厳格化 |
| `NYASH_VERIFY_RET_PURITY=1` | OFF | Any | return ブロックの純粋性検証 |
| `NYASH_ME_CALL_ARITY_STRICT=1` | OFF | Any | me.method の arity 不一致でエラー |
---
参考: [docs/development/architecture/mir-logs-observability.md](../development/architecture/mir-logs-observability.md) / [src/mir/verification/](../../src/mir/verification/)
Reference in New Issue View Git Blame Copy Permalink