Compiler Internals

A história atual do compilador é self-hosted-first. O repositório ainda contém infraestrutura do lado Rust, mas o mapa de implementação ativo que um contribuidor deve aprender hoje vive principalmente em self-hosted/, com o artefato verificado do souc funcionando como a porta de entrada executável para usuários e para a maior parte da verificação da documentação.

Mapa atual da arquitetura

self-hosted/lexer/ e self-hosted/parser/ cuidam da tokenização e da sintaxe.
self-hosted/resolve/ cuida de imports, módulos e resolução de pacotes.
self-hosted/check/ é o coração semântico do compilador, cobrindo tipos, efeitos, epistêmicos, unidades, ownership, padrões, traits, refinamentos e mais.
self-hosted/hlir/ e self-hosted/ir/ cobrem lowering e representações intermediárias voltadas para otimização.
self-hosted/native/, self-hosted/wasm/, self-hosted/gpu/, self-hosted/llvm/ e self-hosted/lsp/ cobrem o trabalho de backend e ferramentas.

A visão voltada ao artefato

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

Como o Rust ainda se encaixa

O antigo crate Rust do compilador não existe mais; o código-fonte do compilador é self-hosted/ (Sounio), e o frontend vive em self-hosted/lexer/ e self-hosted/parser/.
O artefato verificado é construído a partir de self-hosted/ pela cadeia de bootstrap (make build), não pelo Cargo.
Para a documentação, a narrativa mais segura para contribuidores é: use o artefato para o comportamento atual, e use self-hosted/ como o mapa de implementação primário.

Como navegar no código

Comece em self-hosted/compiler/main.sio para a visão voltada ao driver.
Depois avance para os diretórios de subsistema dedicados, em vez de depender apenas dos arquivos de wrapper finos em self-hosted/compiler/.
Use docs/codebase_overview.md e os documentos de implementação como guias de orientação, mas confirme as afirmações a nível de caminho contra a árvore real.

Solução de problemas

Estouro de pilha (Compilador Madaros): O compilador de expressões recursivas pode gerar quadros de pilha extremamente grandes (ex: ~4,85 MB por quadro) quando profundamente aninhado. Isso foi corrigido recentemente na lógica de codegen ao alinhar o dimensionamento dinâmico do quadro às contagens de registradores (align16((*func).reg_count*8)). No entanto, se você enfrentar um SIGSEGV ou falha de segmentação ao compilar funções grandes com operações booleanas aninhadas, certifique-se de aumentar o limite de tamanho da pilha: ulimit -s unlimited.