hakorune/docs/reference/environment-variables.md

# 環境変数リファレンス

Nyashの動作を制御する環境変数の一覧。

---

## MIR Builder検証系

MIRビルダーの動作検証・デバッグ用環境変数。

| 環境変数 | デフォルト | 用途 | 追加Phase |
|---------|----------|-----|-----------|
| `NYASH_ME_CALL_ARITY_STRICT=1` | OFF | me.method呼び出しのarity不一致でエラー返却 | Phase 25.x |
| `NYASH_STATIC_CALL_TRACE=1` | OFF | Static method呼び出しのトレース出力 | Phase 25.x |
| `NYASH_VERIFY_ALLOW_NO_PHI=1` | OFF | PHI検証スキップ（支配・マージ） | - |
| `NYASH_VERIFY_ALLOW_LEGACY=1` | OFF | レガシー命令許可 | - |
| `NYASH_VERIFY_BARRIER_STRICT=1` | OFF | Barrier配置厳密チェック | - |
| `NYASH_VERIFY_EDGE_COPY_STRICT=1` | OFF | Edge copy検証 | - |
| `NYASH_VERIFY_RET_PURITY=1` | OFF | Return block純粋性検証 | - |
| `NYASH_BREAKFINDER_SSA_TRACE=1` | OFF | SSA詳細トレース（BreakFinderBox等） | - |

### 使用例

```bash
# Dev環境で厳密検証（arity不一致でビルドエラー）
NYASH_ME_CALL_ARITY_STRICT=1 cargo test

# トレースのみ（warning表示、エラーにはしない）
NYASH_STATIC_CALL_TRACE=1 ./target/release/hakorune program.hako

# PHI検証を一時的にスキップ
NYASH_VERIFY_ALLOW_NO_PHI=1 ./target/release/hakorune program.hako

# SSA詳細トレース（BreakFinderBox等のデバッグ）
NYASH_BREAKFINDER_SSA_TRACE=1 cargo test mir_stage1_using_resolver_verify 2>&1 | grep "breakfinder/ssa"
```

---

## Stage-1 CLI制御系

Stage-1 CLI（Nyash selfhosting compiler）の制御用環境変数。

| 環境変数 | デフォルト | 用途 | 追加Phase |
|---------|----------|-----|-----------|
| `NYASH_USE_STAGE1_CLI=1` | OFF | Stage-1 CLI有効化 | Phase 25.1 |
| `STAGE1_CLI_DEBUG=1` | OFF | Stage-1 CLI詳細ログ | Phase 25.1 |
| `STAGE1_EMIT_PROGRAM_JSON=1` | OFF | Program JSON出力モード | Phase 25.1 |
| `STAGE1_EMIT_MIR_JSON=1` | OFF | MIR JSON出力モード | Phase 25.1 |
| `STAGE1_BACKEND={vm\|llvm\|pyvm}` | `vm` | 実行バックエンド指定 | Phase 25.1 |
| `STAGE1_SOURCE=<path>` | - | ソースファイルパス | Phase 25.1 |
| `STAGE1_SOURCE_TEXT=<text>` | - | ソーステキスト（inline指定） | Phase 25.1 |
| `STAGE1_PROGRAM_JSON=<path>` | - | Program JSONパス | Phase 25.1 |

### 使用例

```bash
# Stage-1 CLI経由で.hakoファイルをコンパイル
NYASH_USE_STAGE1_CLI=1 STAGE1_SOURCE=program.hako \
  ./target/release/hakorune lang/src/runner/stage1_cli.hako

# Program JSON生成
STAGE1_EMIT_PROGRAM_JSON=1 STAGE1_SOURCE=program.hako \
  ./target/release/hakorune lang/src/runner/stage1_cli.hako

# デバッグログ付き
STAGE1_CLI_DEBUG=1 NYASH_USE_STAGE1_CLI=1 \
  ./target/release/hakorune program.hako
```

---

## Parser制御系

パーサーの動作制御用環境変数。

| 環境変数 | デフォルト | 用途 | 追加Phase |
|---------|----------|-----|-----------|
| `NYASH_PARSER_STAGE3=1` | OFF | Stage-3 parser有効化 | Phase 25.3 |
| `HAKO_PARSER_STAGE3=1` | OFF | Stage-3 parser有効化（.hako側） | Phase 25.3 |
| `NYASH_ENABLE_USING=1` | OFF | using文サポート有効化 | Phase 25.1 |
| `HAKO_ENABLE_USING=1` | OFF | using文サポート有効化（.hako側） | Phase 25.1 |
| `HAKO_STAGEB_APPLY_USINGS=1` | OFF | Stage-B using適用 | Phase 25.1 |

### 使用例

```bash
# using文を使ったプログラムをパース
NYASH_PARSER_STAGE3=1 NYASH_ENABLE_USING=1 \
  ./target/release/hakorune program_with_using.hako
```

---

## デバッグ・観測系

デバッグ・トレース用環境変数。

| 環境変数 | デフォルト | 用途 | 追加Phase |
|---------|----------|-----|-----------|
| `NYASH_CLI_VERBOSE=1` | OFF | 詳細診断情報出力 | - |
| `NYASH_VM_TRACE=1` | OFF | VM実行トレース出力 | - |
| `NYASH_VM_DUMP_MIR=1` | OFF | VM実行前MIR出力 | - |
| `NYASH_DUMP_JSON_IR=1` | OFF | JSON IR出力 | - |
| `NYASH_STAGE1_MIR_DUMP=1` | OFF | Stage-1 MIR出力 | Phase 25.x |
| `NYASH_STAGE1_SCAN_GE=1` | OFF | Compare Ge命令スキャン | Phase 25.x |
| `NYASH_TO_I64_DEBUG=1` | OFF | to_i64変換デバッグ | Phase 25.x |
| `NYASH_FUNCSCANNER_DEBUG=1` | OFF | FuncScanner詳細ログ | Phase 25.3 |
| `NYASH_JOINIR_EXPERIMENT=1` | OFF | JoinIR実験モード（MIR→JoinIR変換テストを有効化） | Phase 26-H/27 |

### 使用例

```bash
# VM実行トレース
NYASH_VM_TRACE=1 ./target/release/hakorune program.hako 2>&1 | grep "vm-trace"

# MIR確認（複数手法）
NYASH_VM_DUMP_MIR=1 ./target/release/hakorune program.hako
./target/release/hakorune --dump-mir program.hako
./target/release/hakorune --emit-mir-json debug.json program.hako

# Stage-1 CLI + MIRダンプ
NYASH_STAGE1_MIR_DUMP=1 cargo test mir_stage1_cli_emit_program_min

# JoinIR実験（テスト限定）
NYASH_JOINIR_EXPERIMENT=1 cargo test --release mir_joinir_funcscanner_trim_auto_lowering -- --ignored
```

---

## プラグイン・Box制御系

プラグインとBox factoryの制御用環境変数。

| 環境変数 | デフォルト | 用途 | 追加Phase |
|---------|----------|-----|-----------|
| `NYASH_DISABLE_PLUGINS=1` | OFF | プラグイン無効化 | - |
| `NYASH_BOX_FACTORY_POLICY={builtin_first\|plugin_first}` | `builtin_first` | Box factory優先順位 | Phase 15.5 |
| `NYASH_FILEBOX_MODE={auto\|plugin\|builtin}` | `auto` | FileBox実装選択 | Phase 15.5 |

### 使用例

```bash
# プラグイン無効で実行（コアBox経路のみ）
NYASH_DISABLE_PLUGINS=1 ./target/release/hakorune program.hako

# Plugin優先でBox生成
NYASH_BOX_FACTORY_POLICY=plugin_first ./target/release/hakorune program.hako
```

---

## 参考

- **MIRログ観測**: [docs/development/architecture/mir-logs-observability.md](../development/architecture/mir-logs-observability.md)
- **Phase 25.4計画**: [docs/private/roadmap2/phases/phase-25.4-naming-cli-cleanup/README.md](../development/roadmap/phases/phase-25.4-naming-cli-cleanup/README.md)
- **MIR検証システム**: [src/mir/verification/](../../src/mir/verification/)