tomoaki/hakorune
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
bfac188732e49ffc6121cb4f1c1646684f35fbdf
hakorune/docs/reference/environment-variables.md
nyash-codex 42f7eaa215 tools: speed up build_llvm NyRT cache + fix Phase 132 smoke counters 
Improvements:
1. NyRT build cache in tools/build_llvm.sh
   - Skip [3/4] rebuild when target/release/libnyash_kernel.a exists
   - Add NYASH_LLVM_FORCE_NYRT_BUILD env var to force rebuild
   - Performance: 60-80% faster on incremental builds

2. Fix Phase 132 smoke test arithmetic bug
   - Replace ((PASS_COUNT++)) with PASS_COUNT=$((PASS_COUNT + 1))
   - Issue: ((x++)) returns 0 when x=0, causes set -e to exit
   - Locations: 8 places in phase132_exit_phi_parity.sh

3. Document NYASH_LLVM_FORCE_NYRT_BUILD in environment-variables.md

Acceptance criteria met:
- Behavior unchanged (first build creates .a, subsequent skip rebuild)
- NYASH_LLVM_FORCE_NYRT_BUILD allows forcing rebuild
- Phase 132 smoke test passes (both cases)
- Behavior-preserving optimization

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2025-12-15 11:06:26 +09:00

15 KiB
Raw Blame History

環境変数リファレンス

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_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 フォールバックを許容（既定は拒否）

LLVM Build Pipeline

tools/build_llvm.sh で使用される環境変数。詳細は phase87-selfhost-llvm-exe-line.md を参照。

Control Variables

変数 デフォルト 説明
NYASH_BIN ./target/release/hakorune hakorune バイナリのパス
NYASH_LLVM_COMPILER harness コンパイラモード: harness または crate
NYASH_LLVM_FEATURE llvm LLVM feature flag (llvm または llvm-inkwell-legacy)
NYASH_LLVM_OBJ_OUT target/aot_objects/<stem>.o オブジェクトファイル出力パス
NYASH_CLI_VERBOSE 0 詳細ビルド出力を有効化

Advanced Control Variables

変数 デフォルト 説明
NYASH_LLVM_SKIP_EMIT 0 オブジェクト生成をスキップ（既存 .o 使用）
NYASH_LLVM_ONLY_OBJ 0 オブジェクト生成後に停止（リンクスキップ）
NYASH_LLVM_SKIP_NYRT_BUILD 0 Nyash Kernel runtime ビルドをスキップ
NYASH_LLVM_FORCE_NYRT_BUILD 0 Nyash Kernel runtime のキャッシュがあっても再ビルドする（tools/build_llvm.sh）
NYASH_LLVM_MIR_JSON (auto) 事前生成 MIR JSON パス (crate mode)
NYASH_LLVM_VALIDATE_JSON 0 MIR JSON スキーマ検証を有効化 (crate mode)
NYASH_LLVM_EMIT obj 出力タイプ: obj または exe (crate only)
NYASH_LLVM_NYRT crates/nyash_kernel/target/release Nyash Kernel runtime パス
NYASH_LLVM_LIBS (empty) 追加リンクライブラリ
NYASH_LLVM_USE_HARNESS (auto) Python harness 使用を強制

LLVM harness debug（Python llvmlite）

変数 デフォルト 説明
NYASH_LLVM_DUMP_IR=1 OFF 生成した LLVM IR を <output>.ll に書き出す（harness 実装側の簡易ダンプ）
NYASH_LLVM_DUMP_IR=/path/to/out.ll unset 生成した LLVM IR を指定パスに書き出す（tools/build_llvm.sh の内部経由でも可）
NYASH_LLVM_TRACE_PHI=1 OFF PHI 配線/スナップショット解決の詳細トレース（Python backend）
NYASH_LLVM_TRACE_VALUES=1 OFF value 解決トレース（Python backend）
NYASH_LLVM_TRACE_OUT=/tmp/llvm_trace.log unset LLVM トレースの出力先（未指定なら stdout）
NYASH_LLVM_STRICT=1 OFF Python LLVM backend を Fail-Fast モードにする（snapshot miss / use-before-def / PHI不整合 を即エラー化）
NYASH_LLVM_PHI_STRICT=1 OFF PHI の default-zero フォールバックを禁止し、incoming miss を即エラー化

使用例

# 基本ビルド（全デフォルト）
tools/build_llvm.sh program.hako -o output

# 詳細デバッグ
NYASH_CLI_VERBOSE=1 tools/build_llvm.sh program.hako -o output

# Crate mode + JSON検証
NYASH_LLVM_COMPILER=crate NYASH_LLVM_VALIDATE_JSON=1 \
  tools/build_llvm.sh program.hako -o output

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_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
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 72 整理版)

JoinIR は制御構造を関数呼び出し + 継続に正規化する IR 層。フラグは config/env のポリシーで集約するよ。

ポリシー入口

  • joinir_core_enabled() … JoinIR は常に ON。NYASH_JOINIR_CORE は deprecated で無視（0 を指定すると警告だけ出す）。
  • joinir_dev_enabled() … NYASH_JOINIR_DEV=1 または JoinIR debug level > 0 で ON（開発者向け束ねスイッチ）。

LoopBuilder は物理削除済みで、JoinIR を OFF にするモードは存在しない。

Core（本線化対象）

変数 デフォルト 説明
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 削除済み Phase 124 で削除: hako_check は JoinIR 専用化。環境変数不要。

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 / 廃止候補

変数 状態 説明
NYASH_JOINIR_CORE Deprecated JoinIR 本線の ON/OFF トグルだったが、LoopBuilder 削除後は無効化不可。設定しても警告のみにして無視する。
HAKO_JOINIR_NESTED_IF Deprecated候補 Route B nested if。
HAKO_JOINIR_READ_QUOTED / _IFMERGE Deprecated候補 read_quoted JoinIR 実験。

使用例

# JoinIR は常に ON。Stage-3（推奨）
env NYASH_FEATURES=stage3 ./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 / Phase 72 フラグ整理

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 不一致でエラー
NYASH_MIR_DISABLE_OPT=1 OFF Any MIR Optimizer 全体を無効化（開発/診断用、src/mir/optimizer.rs）
NYASH_TRACE_VARMAP=1 OFF Any MirBuilder.variable_map の状態をトレース出力（[varmap/<tag>] {name=ValueId(..),..}）。JoinIR loop 統合のデバッグ用。
NYASH_DCE_TRACE=1 OFF Any DCE パスが削除した純粋命令を stderr にログ出力（src/mir/passes/dce.rs）。

MIR / PHI diagnostics（dev-only）

変数 デフォルト 適用経路 説明
NYASH_PHI_TYPE_DEBUG=1 OFF Any PhiTypeResolver の詳細トレース（[phi/type] ...）
NYASH_PHI_META_DEBUG=1 OFF Any PHI metadata の伝播トレース（PHI dst / incoming の追跡）

参考: docs/development/architecture/mir-logs-observability.md / src/mir/verification/