Validação

Base atual

Os gates registados mais recentes no anfitrião de desenvolvimento Windows x64 (clang-cl e SDK do LLVM 23.1.2, /MT, _ITERATOR_DEBUG_LEVEL=0); os passos posteriores registam os seus em .agents/00-finished.md:

Executar o gate

A partir de uma shell de programador do Visual Studio x64 com C:\Program Files\LLVM\bin no PATH (a seleção automática do SDK reutiliza thirdparty/):

cmake --preset debug --fresh -DBUILD_TESTING=ON -G Ninja -DCMAKE_C_COMPILER=clang-cl -DCMAKE_CXX_COMPILER=clang-cl
cmake --build build/debug
ctest --preset debug-fast                  # during development
ctest --preset debug -j 16                 # full mode, at feature completion
cmake --build build/debug --target check-quality      # changed files, one unit per header
cmake --build build/debug --target check-quality-all  # whole tree

• CLAUSE_TEST_MODE=fast executa os corpora golden em O0 posicional mais o projeto O2 com a especialização desativada, executa as mutações uma vez e salta os testes full_only (projetos consumidores separados como runtime_generated_link, medições, a auditoria library_freshness ao OTP do anfitrião, e os fluxos de trabalho lentos linking_lto, linking_exports, linking_compile_cache, programs_compile e transforms_cache). O modo completo (predefinido) executa todas as combinações de driver/política.
• Os testes longos conduzidos por um script Python ou CMake têm um COST fixo no CTest: o CTest aprende o custo de um wrapper a partir do seu próprio tempo de CPU, pequeno, e iniciá-los-ia em último lugar.
• Os testes sensíveis à carga (CLAUSE_LOAD_SENSITIVE_TESTS no CMakeLists.txt de topo: frontend_cli, codegen_examples, linking_debugger, executables_applications) só excediam o tempo limite ou perdiam corridas de temporização numa execução paralela completa. Têm DEPENDS de todos os outros testes, pelo que começam depois de terminar o resto da seleção e têm os processadores só para si; uma dependência que falhe não os faz saltar.
• CLAUSE_TEST_TIMEOUT_SCALE=N multiplica os limites por execução do executor de goldens (60 s) e do executor de casos semânticos (15 s) para compilações instrumentadas.
• check-quality, make format e make-format.bat abrangem os ficheiros alterados desde HEAD mais os ficheiros não seguidos; cmake/quality_scope.py acrescenta, para cada cabeçalho alterado, uma unidade de tradução que o inclui (o seu próprio código-fonte, ou o primeiro utilizador, a partir dos dados de dependências do Ninja de qualquer configuração; os restantes dependentes do cabeçalho ficam para check-quality-all na verificação completa) e, para o clang-tidy, as unidades cujo comando de compilação difere do registado pela última execução aprovada (build/debug/quality/tidy-commands.json), pelo que uma edição de uma regra de compilação volta a verificar apenas as unidades que altera. As alterações a .clang-tidy ou aos scripts do tidy selecionam tudo, tal como as edições de regras de compilação antes da primeira execução registada.
• CLAUSE_OPTIMIZED_COMPILER (por omissão ON) compila o clau e as bibliotecas do compilador otimizados também nas compilações Debug, mantendo a sua informação de depuração e os orçamentos de inferência Debug; os testes passam a maior parte do tempo no clau. Quando for preciso percorrer passo a passo uma falha do compilador, configure com -DCLAUSE_OPTIMIZED_COMPILER=OFF, recompile e volte a executar o teste que falha.
• Os programas de teste não contêm informação de depuração (sem PDBs); configure com -DCLAUSE_TEST_DEBUG_INFO=ON para os recompilar para um depurador. Os consumidores nativos aninhados ligam o runtime da compilação principal através de ClauseRuntimeTargets.cmake em vez de o compilar novamente; só runtime_link compila o runtime de forma autónoma.
• Os limiares e as supressões nunca são aumentados para passar o gate. Estão configuradas duas exceções de terceiros (decisão do utilizador): cmake/tidy_filter.py descarta os relatórios do analisador estático localizados em cabeçalhos do Boost (falsos positivos do armazenamento de limbs do Boost.Multiprecision em Linux que reescrever o código chamador apenas desloca) e conta-os na saída, e bugprone-exception-escape ignora bad_array_new_length (os construtores de movimento de map/set do MSVC alocam; uma falha de alocação é, de qualquer modo, fatal).
• O clang-tidy verifica os cabeçalhos do projeto em todos os anfitriões: o filtro de cabeçalhos aceita os separadores / e \.

Linux

O mesmo gate corre em Linux com o SDK Linux do LLVM 23.1.2 fixado como compilador do anfitrião (CC/CXX a partir do seu bin/), a libstdc++ do sistema, Ninja e CMake 3.28 ou mais recente. O Boost 1.90 e o toml++ 3.4.0 vêm de pacotes instalados ou são extraídos para thirdparty/ (boost_1_90_0/, tomlplusplus-3.4.0/); só o Windows os descarrega. O ld.lld do arquivo da release liga a ICU 70 (Ubuntu 22.04) e o seu lldb liga o Python 3.14; em anfitriões sem eles, linking_lto precisa da ICU 70 em LD_LIBRARY_PATH, e linking_debugger usa o GDB.

cmake --preset debug --fresh -G Ninja -DBUILD_TESTING=ON
cmake --build build/debug
ctest --preset debug -j 16

check-quality (Lizard, clang-tidy) corre apenas no anfitrião de desenvolvimento Windows; os outros anfitriões compilam e executam os testes (esteve limpo em Linux uma vez, ver o histórico).

Outros alvos

Os alvos de 32 bits e ARM são verificados sem um compilador compilado para eles (não existe SDK do LLVM para esses anfitriões):

• Uma compilação só do runtime (-DCLAUSE_BUILD_COMPILER=OFF -DBUILD_TESTING=ON) para o alvo executa aí os testes do runtime e da ABI: nativamente, num userland do alvo (chroot) ou através do emulador do anfitrião (qemu binfmt).
• tests/compiler/executables/cross.py executa todos os goldens de executáveis e fixtures de programas com o clau deste anfitrião, --target-triple, o arquivo do runtime dessa compilação e um --linker que alcança as bibliotecas do alvo (run.py --target-option passa-os adiante).

Fixtures e proveniência

• As compilações e os testes normais não precisam do OTP nem do seu código-fonte. Os goldens foram gerados uma vez a partir do OTP e estão no repositório com hashes; as verificações de hash são executadas antes de qualquer fixture ser usada.
• Dezanove corpora de padrões/guards contêm 67 748 valores/erros nativos esperados e 106 linhas de aceitação semântica. Cada corpus nativo executa os drivers posicional e de projeto em O0/O2 com a especialização ativada e desativada, com chamadas locais e remotas.
• As entradas Erlang no repositório são de autoria local (tests/fixtures/patternmatch/fragments/, semantic/headers/ do pré-processador); fixture_sources impõe o isolamento em relação ao código-fonte do OTP.
• Seis fixtures de programas finais (tests/fixtures/programs/) contêm goldens de stdout/estado de saída do OTP e os seus diagnósticos de compilação; programs_compile verifica-os sem OTP e tests/compiler/programs/regenerate.py --check reprodu-los com o OTP (mapa das fixtures).
• Os goldens de impressão de termos (tests/fixtures/printing/) contêm o texto de ~w e de erlang:display/1 do OTP para 9 542 valores, mais o stdout do OTP de chamadas display compiladas; tests/compiler/printing/regenerate.py --check reprodu-los (notas das fixtures).
• Os casos golden de executáveis (tests/fixtures/executables/) são diretórios de código-fonte mais um golden.json com o stdout/estado de saída do OTP e um padrão de stderr escrito à mão; tests/compiler/executables/run.py liga e executa cada um sob a matriz de política/driver (CTest executables_<case>), e regenerate.py --check reprodu-los com o OTP (notas dos casos).
• A regeneração e as auditorias em direto são explícitas: -DCLAUSE_OTP_AUDITS=ON e tests/compiler/patternmatch/regenerate.py (instruções). Nada atualiza os goldens nem o pin silenciosamente.

Conceção dos testes

O comportamento é testado através da CLI real, dos objetos emitidos, de consumidores nativos ligados e dos goldens do OTP. Os testes unitários dedicados permanecem apenas onde o código-fonte não consegue alcançar o estado, cada um com o seu propósito indicado no teste:

• Orçamentos injetados e falhas de alocação/E/S (project_limits, project_creation_failure, codegen_limits, codegen_write_failure, runtime_lifecycle_failure, pontos de injeção de falhas em chamadas geradas).
• Invariantes de posse privada, de handles inválidos/obsoletos e de reversão no analisador sintático, no grafo de tipos semântico e no backend.
• Validação de palavras em bruto e limites de termos de 32/64 bits (runtime_immediate, runtime_term_tag, abi_integers).
• Falhas do destino de diagnósticos e o instantâneo estável dos IDs de funcionalidades.

Os casos de capacidades do sistema de ficheiros (ligações, aliases por maiúsculas/minúsculas) relatam testes saltados por caso; nunca substituem a aprovação de um teste completo.

Estado por plataforma e sanitizers

• Execução de código gerado nativo: Windows x64; Linux x86-64. Os resultados de 32 bits e ARM (testes do runtime e goldens ligados de forma cruzada) estão no histórico.
• Apple Silicon: não validado desde que o backend existe.
• ASan, UBSan e LeakSanitizer no compilador e no runtime: Linux x86-64, uma única configuração Debug combinada (-fsanitize=address,undefined -fno-sanitize=vptr -fno-sanitize-recover=undefined), CTest completo com CLAUSE_TEST_TIMEOUT_SCALE=10 (o código instrumentado corre várias vezes mais devagar): nenhum relatório dos sanitizers. O compilador, o runtime e os programas de teste são instrumentados; os programas que o clau liga obtêm o runtime do sanitizer a partir de um wrapper clang++ no PATH, e o seu código gerado não é instrumentado. Os quatro testes de recusa injetada do anfitrião (codegen_failure_*, runtime_lifecycle_failure, runtime_memory) estão fora do âmbito do ASan: o seu operator new aborta perante um tamanho impossível em vez de lançar uma exceção.
• ThreadSanitizer: Linux x86-64, o mesmo âmbito de instrumentação com -fsanitize=thread; o CTest completo e os testes de concorrência, cinco vezes cada, não comunicam nenhuma corrida. Também fora do âmbito: os dois testes que substituem operator new.
• Em Windows, o SDK do LLVM pré-compilado continua a entrar em conflito com o código instrumentado (annotate_string 0 vs 1).
• O ASan apenas do runtime passa em Windows com sondas Release, /EHsc /fsanitize=address, /MT, a biblioteca de importação do ASan e o thunk de runtime estático do Clang, e a DLL do ASan no PATH.
• Execuções históricas em macOS arm64 (2026-09-19/20) passaram compilações Debug completas, C++26, ASan+UBSan, apenas do compilador e apenas do runtime para as fases do analisador sintático e dos projetos; são anteriores ao backend.

Benchmarks

Comparação manual de desempenho com o Erlang/OTP. Nunca faz parte do CTest, do gate de commit nem de check-quality, e só ela precisa de um Erlang/OTP no anfitrião; os resultados são evidência específica do anfitrião, não resultados do gate.

make-benchmark.bat                         # Windows; set JOBS=N to cap parallel builds
make-benchmark.bat --repeat 9 --only bench_gc,bench_msg
make-benchmark.bat --cpus all                 # unpinned set; default --cpus performance
make benchmark BENCH_ARGS="--baseline HEAD~5"   # other hosts

• Ambos configuram e compilam um clau e um runtime Release em build/bench e depois executam benchmarks/run.py (--help lista as suas opções).
• Programas: benchmarks/bench_*.erl com bench_util.erl, compilados sem alterações pelo erlc e por clau -O2. Cada um cronometra os seus kernels com erlang:monotonic_time/1 após uma chamada de aquecimento e imprime BENCH <name> <nanoseconds>: geração de dados, processamento de dados, recolha de lixo, passagem de mensagens, E/S de ficheiros (num diretório de trabalho temporário vazio em build/bench/runs, dentro do repositório para que uma exclusão do antivírus para o repositório o abranja), sockets de loopback e bibliotecas (libraries.qlc: transformações de consultas por qlc_pt e módulos com a forma dos casos de qlc_SUITE, cronometrados em conjunto). As contagens de iterações fazem cada kernel durar 1-2 s no OTP, pelo que a resolução do temporizador e o ruído do anfitrião permanecem pequenos em comparação; os kernels de sockets aumentam o trabalho por ligação, não o número de sockets. Fora da cronometragem, o aquecimento e as chamadas cronometradas esperam, cada um, até que os processos que lançaram terminem (erro processes_left após 10 s). Cada kernel executa no seu próprio processo novo, que termina antes de o kernel seguinte começar, pelo que nenhum kernel paga pelos heaps que um anterior fez crescer.
• Cada execução de programa tem o seu próprio objeto job de Windows ou sessão POSIX; a execução seguinte começa quando todos os seus processos tiverem terminado, e os restantes ainda vivos 30 s após a saída são terminados e comunicados como falha.
• CPUs: todos os processos de uma execução, tanto do OTP como do Clause, executam no conjunto --cpus: performance (por omissão: os núcleos da EfficiencyClass mais elevada em Windows, /sys/devices/cpu_core/cpus ou a maior cpu_capacity em Linux, pelo que são os núcleos P de um CPU híbrido e todos os CPUs nos restantes casos), all, uma lista como 0-15 ou 2,4,6, ou uma máscara hexadecimal como 0x5554. Em Windows, o objeto job da execução impõe o limite de afinidade antes de o programa retomar; em Linux, o programa define-o antes de exec; macOS não permite fixar a afinidade e executa sem ela. Tanto o OTP como o Clause iniciam um escalonador online por CPU do conjunto, sem vinculação a CPUs individuais. O cabeçalho do relatório e cada registo do histórico (cpus) indicam o conjunto; as razões de execuções em conjuntos diferentes não são comparáveis.
• Sistemas, no mesmo anfitrião numa só execução, intercalados: o OTP com a sua variante por omissão (JIT), o OTP -emu_flavor emu quando instalado (o instalador Windows só inclui o JIT, pelo que essas colunas mostram n/a), o Clause HEAD em O2 e com --lto, e um commit anterior do Clause (por omissão: o commit mais recente com pelo menos um dia a mais do que HEAD; --baseline REV, --no-baseline) compilado num worktree em cache em build/bench-base/<hash> que partilha thirdparty/.
• Relatório: por kernel, a mediana de --repeat execuções (por omissão 3) em milissegundos com seis casas decimais e a sua dispersão, a variação do Clause O2 em relação a cada sistema (+N%: o Clause é mais rápido, o outro demora mais N%; -N%: o Clause demora mais N%; (Fx) a razão dos tempos) com uma média geométrica, --lto em relação ao OTP e ao O2, os tempos totais dos programas incluindo o arranque, os tamanhos dos executáveis, as falhas e os tempos esgotados (--timeout, 600 s por execução). Uma execução por omissão mede durante cerca de 15 minutos.
• Tamanhos dos executáveis, em bytes: cada programa em -O2, com --lto e em -O0 (uma compilação adicional apenas medida, nunca executada; ambas omitidas por --no-lto) e a referência em -O2, com uma linha de total e as variações O2 vs O0, --lto vs O2, --lto vs O0 e O2 vs referência (-N% menor); e clau em HEAD e na referência. O histórico guarda-os como sizes_bytes (programs: programa → coluna → bytes, clau: head/baseline → bytes; null quando uma compilação falhou).
• Histórico: benchmarks/history/<host>.json guarda um registo por dia de execução (data da execução, hash e data do commit de HEAD, medianas do Clause, do OTP e da referência, tamanhos e razões dos tempos do Clause otp_ratio e baseline.ratio por kernel), benchmarks/history/reports/<host>/<day>-<hash>.txt os relatórios de texto; uma nova execução no mesmo dia substitui ambos. Os registos e os relatórios executados mais de 183 dias antes do mais recente são eliminados; uma execução com alterações de código-fonte não submetidas é comunicada mas não registada. As tabelas do histórico do relatório mostram as razões dos últimos 8 dias de execução, que continuam comparáveis quando os kernels mudam o seu trabalho; os registos anteriores ao redimensionamento para 1-2 s mantêm apenas as suas razões. O diretório do histórico é ignorado pelo git: fica no anfitrião que o executou.
• Listagens: com --listings, antes de medir, uma execução escreve as listagens --print-asm e --print-ir de cada programa (com bench_util, --entry <program>, para que o código de biblioteca inalcançável fique de fora como no executável) ao lado dos relatórios como <program>.debug.asm / <program>.debug.ll (-O0) e <program>.release.asm / <program>.release.ll (-O2, o código que a coluna clause-o2 executa), substituindo as listagens da execução anterior, incluindo com --no-history e alterações não submetidas. --print-ir é a IR antes do pipeline do LLVM; os comentários do assembly citam a IR depois dele. Um programa que não compila perde as suas listagens obsoletas.

Histórico

Condensado a partir dos antigos registos por passo (originais no histórico do Git até ao commit 2777c98). Salvo indicação em contrário: Windows x64, LLVM 23.1.2, pin 21776803ecd1, oráculo OTP 29.1.1 / ERTS 17.1. Os números de testes são execuções completas do CTest aprovadas, com zero testes saltados.

PG = passo do plano de padrões/guards; os registos dos passos do plano 11 estão arquivados em .agents/00-finished.md.