hakorune/docs/reference/environment-variables.md

環境変数リファレンス

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 経路の例

# 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_PARSER_STAGE3=1	OFF	Any	Stage-3 構文を許可
HAKO_PARSER_STAGE3=1	OFF	Any	.hako 向け Stage-3 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)

# Ny compiler 経路で Program(JSON v0)→MIR→dump を観測
NYASH_USE_NY_COMPILER=1 \
NYASH_PARSER_STAGE3=1 HAKO_PARSER_STAGE3=1 \
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
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
`NYASH_FILEBOX_MODE={auto	plugin	builtin}`	auto

---

JoinIR 実験 (Phase 27+)

JoinIR は制御構造を関数呼び出し + 継続に正規化する IR 層（実験中）。

変数	デフォルト	適用経路	説明
NYASH_JOINIR_EXPERIMENT=1	OFF	Any	JoinIR 実験モード メイントグル
NYASH_JOINIR_HEADER_EXP=1	OFF	Any	Header PHI bypass 有効化（dev-only）
NYASH_JOINIR_EXIT_EXP=1	OFF	Any	Exit PHI 実験（dev-only）
NYASH_JOINIR_LOWER_FROM_MIR=1	OFF	Any	MIRベース lowering 有効化（dev-only）
NYASH_JOINIR_LOWER_GENERIC=1	OFF	Any	構造ベースのみで Case-A 判定（関数名フィルタを外す）
NYASH_JOINIR_VM_BRIDGE=1	OFF	Any	VM bridge 経路（Route B）を有効化
NYASH_JOINIR_LLVM_EXPERIMENT=1	OFF	llvm-harness	LLVM 経路で JoinIR を試す（L-4.3a）

JoinIR 各変数の詳細

NYASH_JOINIR_EXPERIMENT

• 対象: skip / trim / Stage-1 UsingResolver / Stage-B BodyExtractor / Stage-B FuncScanner
• 役割: JoinIR runner / JoinIR VM bridge / 各種テストを有効化する dev トグル

NYASH_JOINIR_VM_BRIDGE

• 対象: 上記と同じ
• 役割: VM モードで Route B（MIR→JoinIR→MIR→VM）を試す経路を有効化
• 重要: 実際に「JoinIR→VM 実行」まで行くのは Phase 32 時点では skip / trim に限定。Stage-1 / Stage-B は lowering + Bridge の健全性確認まで（実行は VM Route A）

NYASH_JOINIR_LOWER_GENERIC (Phase 32 L-1.2)

• 既定 OFF: minimal 4 本（skip_ws / trim / append_defs / Stage-1 minimal）のみ LoopToJoinLowerer 対象
• ON: LoopRegion / LoopControlShape / LoopScopeShape の構造条件を満たすループ全般を Case-A 候補として扱う
• 注意: Phase 32 では Stage-B / Stage-1 本線については「構造テスト・JoinIR 構造観測」用途で使うトグルであり、「意味論の本番切り替え」ではない

NYASH_JOINIR_LLVM_EXPERIMENT (Phase 32 L-4.3a)

• 前提: NYASH_JOINIR_EXPERIMENT=1 と NYASH_LLVM_USE_HARNESS=1 が必要
• 役割: LLVM 経路（llvmlite ハーネス）で JoinIR を経由して PHI 問題を回避する実験
• 動作: Main.skip/1 を JoinIR 経由で MIR' に変換し、元の PHI 問題のある関数を置換
• 検証: Route A (MIR→LLVM) の PHI エラーが Route B (MIR→JoinIR→MIR'→LLVM) で解消されることを実証済み

JoinIR 使用例

# JoinIR 実験モード有効化（基本）
NYASH_JOINIR_EXPERIMENT=1 ./target/release/hakorune program.hako

# Header PHI bypass 併用
NYASH_JOINIR_EXPERIMENT=1 NYASH_JOINIR_HEADER_EXP=1 ./target/release/hakorune program.hako

# Stage-B JoinIR lowering を観測したい場合（Phase 32 開発用）
# → JoinIR lowering + JoinIR→MIR Bridge が走り、ログで JoinIR 構造が確認できる
# → 実際の実行は VM Route A にフォールバック
NYASH_JOINIR_EXPERIMENT=1 \
NYASH_JOINIR_VM_BRIDGE=1 \
NYASH_JOINIR_LOWER_GENERIC=1 \
  ./target/release/hakorune --dump-mir apps/tests/stageb_case.hako

# LLVM 経路で JoinIR を使う（L-4.3a）
# Route A (MIR→LLVM) の PHI エラーが Route B (MIR→JoinIR→MIR'→LLVM) で解消される
env NYASH_PARSER_STAGE3=1 HAKO_PARSER_STAGE3=1 \
    NYASH_DISABLE_PLUGINS=1 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 / Phase 32 README

---

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 / src/mir/verification/