編譯器內部結構

目前編譯器嘅發展方向係以「自託管優先」(self-hosted-first)。程式庫入面仍然有 Rust 寫嘅基礎設施，但而家貢獻者應該要了解嘅主要實作地圖，已經移咗去 self-hosted/ 嗰邊。經檢查過嘅 souc 執行檔會作為用戶嘅主要入口，亦都係大部份文檔驗證嘅基礎。

目前嘅架構地圖

• self-hosted/lexer/ 同 self-hosted/parser/ 負責處理詞法分析 (tokenization) 同語法 (syntax)。
• self-hosted/resolve/ 負責處理引入 (imports)、模組 (modules) 同套件解析。
• self-hosted/check/ 係編譯器語意嘅核心，涵蓋類型、副作用 (effects)、認知 (epistemics)、單位 (units)、所有權 (ownership)、模式 (patterns)、特徵 (traits)、精化 (refinements) 等等。
• self-hosted/hlir/ 同 self-hosted/ir/ 涵蓋向下轉換 (lowering) 同埋以最佳化為目標嘅中間表示 (IR)。
• self-hosted/native/、self-hosted/wasm/、self-hosted/gpu/、self-hosted/llvm/ 同 self-hosted/lsp/ 負責後端同工具開發。

從執行檔角度睇

export SOUC_BIN="$(pwd)/bin/souc"
"$SOUC_BIN" info
"$SOUC_BIN" --help

Rust 仲有咩用？

• crates/souc/ 仍然存在，但喺目前嘅檔案樹入面，佢已經唔係解釋大部份語言同後端開發喺邊度進行嘅最好切入點。
• 你今日執行嘅檢查過嘅執行檔，係透過程式庫嘅構建同發佈機制產生嘅，所以 Rust 嗰邊嘅代碼對產生執行檔同連接仍然好重要。
• 對於文檔，最穩陣嘅貢獻者視角係：用執行檔去了解目前嘅行為，並將 self-hosted/ 作為主要嘅實作地圖。

點樣導航代碼庫

• 由 self-hosted/compiler/main.sio 開始睇驅動程式 (driver) 嘅視角。
• 然後向外睇各個專屬子系統嘅目錄，而唔好單靠 self-hosted/compiler/ 入面嗰啲好薄嘅包裝檔。
• 用 docs/codebase_overview.md 同埋實作文件作為方向指引，但記得要對照實際嘅檔案樹去確認路徑層面嘅聲明。

疑難排解

• 堆疊溢位 (Stack Overflow - Madaros 編譯器)： 遞迴表達式編譯器喺深度嵌套嗰陣，可能會產生極之大嘅堆疊框架（例如每個框架大約 4.85 MB）。呢個問題最近已經喺即時代碼生成邏輯入面解決咗，方法係將動態框架大細同暫存器數量對齊 (align16((*func).reg_count*8))。不過，如果你喺編譯包含嵌套布林運算嘅大函數時，遇到 SIGSEGV 或分段錯誤 (segfault)，請確保你增加咗堆疊大細限制：ulimit -s unlimited。