tomoaki/hakorune

Fork 0

Files

nyash-codex 8fd3a2b509 docs: restore docs/private/roadmap from 7b4908f9 (Phase 20.31)

2025-10-31 18:00:10 +09:00

8.2 KiB

Raw Blame History

Phase 31.3 Quick Start Guide

すぐに始められるSelfhost綺麗綺麗計画の最初のステップ

Week 1 の即座実行タスク（今すぐ開始可能！）

タスク1: コード品質分析（15分）

cd /home/tomoaki/git/hakorune-selfhost

# Compiler分析
bash -c 'for file in selfhost/compiler/pipeline_v2/*.hako; do \
  lines=$(wc -l < "$file"); \
  name=$(basename "$file"); \
  echo "$lines $name"; \
done | sort -rn' > docs/private/roadmap/phases/phase-31.3/QUALITY_ANALYSIS_COMPILER.txt

# VM分析
bash -c 'for file in selfhost/hakorune-vm/*.hako; do \
  lines=$(wc -l < "$file"); \
  name=$(basename "$file"); \
  echo "$lines $name"; \
done | sort -rn' > docs/private/roadmap/phases/phase-31.3/QUALITY_ANALYSIS_VM.txt

# 結果確認
cat docs/private/roadmap/phases/phase-31.3/QUALITY_ANALYSIS_COMPILER.txt | head -10
cat docs/private/roadmap/phases/phase-31.3/QUALITY_ANALYSIS_VM.txt | head -10

期待結果:

# Compiler TOP 10
535 pipeline.hako               ⚠️ 巨大関数（要分割）
249 using_resolver_box.hako    ⚠️ 要リファクタリング
209 stage1_extract_flow.hako
187 local_ssa_box.hako
...

# VM TOP 10
315 closure_call_handler.hako  ⚠️ 巨大関数（要分割）
267 terminator_handler.hako    ⚠️ 要リファクタリング
235 hakorune_vm_core.hako
234 phi_handler.hako
...

タスク2: TraceBox実装（30分）

Step 1: ディレクトリ作成

mkdir -p selfhost/shared/trace

Step 2: TraceBox実装

ファイル: selfhost/shared/trace/trace_box.hako

// TraceBox - 統一トレース出力システム
// Rust LoopTraceBox の Hakorune版移植
// Usage: HAKO_TRACE=1 で有効化

static box TraceBox {
  enabled: IntegerBox
  prefix: StringBox

  // Constructor
  birth(enabled, prefix) {
    me.enabled = enabled
    me.prefix = prefix
  }

  // Basic logging
  log(message) {
    if me.enabled == 1 {
      print(me.prefix + message)
    }
  }

  // Conditional logging
  log_if(condition, message) {
    if me.enabled == 1 && condition == 1 {
      print(me.prefix + message)
    }
  }

  // Formatted logging with value
  log_value(label, value) {
    if me.enabled == 1 {
      print(me.prefix + label + ": " + value)
    }
  }

  // Multi-value logging
  log_values(label, value1, value2) {
    if me.enabled == 1 {
      print(me.prefix + label + ": " + value1 + ", " + value2)
    }
  }

  // Error logging (always enabled)
  error(message) {
    print("[ERROR] " + me.prefix + message)
  }
}

行数: 約50行 ✅

Step 3: hako.toml に追加

ファイル: selfhost/shared/hako.toml（既存ファイルに追加）

[exports]
# 既存のexports...
trace = "trace/trace_box.hako"

Step 4: 動作確認

テストファイル: apps/examples/trace_test.hako

using selfhost.shared.trace as TraceBox

static box Main {
  main() {
    // トレース有効（enabled=1）
    local trace = new TraceBox(1, "[Test] ")

    trace.log("Starting test")
    trace.log_value("x", 42)
    trace.log_values("a, b", 10, 20)
    trace.log_if(1, "Condition is true")
    trace.log_if(0, "This should NOT appear")

    // トレース無効（enabled=0）
    local silent = new TraceBox(0, "[Silent] ")
    silent.log("This should NOT appear")

    // エラーは常に表示
    trace.error("This is an error")

    return 0
  }
}

実行:

./target/release/hakorune apps/examples/trace_test.hako

期待出力:

[Test] Starting test
[Test] x: 42
[Test] a, b: 10, 20
[Test] Condition is true
[ERROR] [Test] This is an error

タスク3: 既存コードへのTraceBox適用（30分）

Step 1: pipeline.hakoの冒頭でTraceBox初期化

ファイル: selfhost/compiler/pipeline_v2/pipeline.hako（既存、編集）

// 既存のusing文に追加
using selfhost.shared.trace as TraceBox

flow PipelineV2 {
  lower_stage1_to_mir_trace(ast_json, prefer_cfg, trace_flag) {
    // TraceBox初期化
    local trace = new TraceBox(trace_flag, "[Pipeline] ")

    trace.log("Start: prefer_cfg=" + prefer_cfg)

    // 既存のコード...
    if ast_json == null {
      trace.error("ast_json is null")
      return EmitReturnBox.emit_return_int2(0, 0)
    }

    // ... 処理 ...

    trace.log("Complete")
    return mir_json
  }
}

Step 2: 既存のprint()をtraceに置換（5-10箇所）

置換パターン:

// Before
print("[DEBUG] Some message: " + value)

// After
trace.log_value("Some message", value)

対象ファイル（優先順位順）:

pipeline.hako（3-5箇所）
local_ssa_box.hako（2-3箇所）
using_resolver_box.hako（1-2箇所）

Step 3: 動作確認

# トレース無効（デフォルト）
./target/release/hakorune apps/selfhost-compiler/main.hako

# トレース有効
# 注: HAKO_TRACE環境変数の実装は後で（今は trace_flag=1 で直接指定）
# 暫定的に pipeline.hako 内で trace_flag を 1 にして実行

Week 1 の達成目標

✅ 完了チェックリスト

タスク1: コード品質分析完了（QUALITY_ANALYSIS_*.txt作成）
タスク2: TraceBox実装完了（trace_box.hako, 50行）
タスク3: 既存コードへのTraceBox適用（5-10箇所）
テスト: trace_test.hako実行成功
ドキュメント: SELFHOST_QUALITY_REPORT.md作成開始

📊 成果物

QUALITY_ANALYSIS_COMPILER.txt: Compiler品質分析
QUALITY_ANALYSIS_VM.txt: VM品質分析
selfhost/shared/trace/trace_box.hako: TraceBox実装（50行）
apps/examples/trace_test.hako: TraceBoxテスト
既存コードのTraceBox適用（5-10箇所）

📈 削減/追加行数

追加: +50行（TraceBox）
変更: 5-10箇所（既存のprint()をtraceに置換）

Week 2 の準備（余裕があれば）

CompilerConfigBox実装の準備

ファイル: selfhost/compiler/pipeline_v2/compiler_config_box.hako（新規）

// CompilerConfigBox - コンパイラ設定の一元管理
// Rust ConfigBox の Hakorune版

box CompilerConfigBox {
  prefer_cfg: IntegerBox
  trace_enabled: IntegerBox
  trace: TraceBox

  birth(prefer_cfg, trace_enabled) {
    me.prefer_cfg = prefer_cfg
    me.trace_enabled = trace_enabled
    me.trace = new TraceBox(trace_enabled, "[Config] ")

    me.trace.log_value("prefer_cfg", prefer_cfg)
    me.trace.log_value("trace_enabled", trace_enabled)
  }

  get_prefer_cfg() {
    return me.prefer_cfg
  }

  get_trace() {
    return me.trace
  }
}

行数: 約30行

トラブルシューティング

Q1: TraceBoxのusing文でエラーが出る

エラー:

Unknown module: selfhost.shared.trace

解決:

selfhost/shared/hako.toml に trace = "trace/trace_box.hako" を追加したか確認
ファイルパスが正しいか確認: selfhost/shared/trace/trace_box.hako
hako.tomlのsyntaxエラーがないか確認（TOML形式）

Q2: TraceBox.birth()でエラーが出る