Build, comandos e integração contínua
Makefile vivo
Targets extraídos diretamente do Makefile:
| Target | Dependências | Linha |
|---|---|---|
all | $(FERRAMENTA) $(BIBLIOTECA) | 33 |
biblioteca | $(BIBLIOTECA) | 48 |
test | $(FERRAMENTA) $(BIBLIOTECA) $(TESTE_BIBLIOTECA) | 55 |
test-v | $(FERRAMENTA) $(BIBLIOTECA) $(TESTE_BIBLIOTECA) | 59 |
test-biblioteca | $(TESTE_BIBLIOTECA) | 63 |
smoke | test | 67 |
smoke-v | test-v | 69 |
test-portabilidade | $(FERRAMENTA) $(BIBLIOTECA) | 76 |
test-portabilidade-v | $(FERRAMENTA) $(BIBLIOTECA) | 80 |
test-sanitize | — | 89 |
test-matriz | — | 98 |
fuzz | $(FERRAMENTA) | 102 |
test-checkout | — | 106 |
exemplos | $(FERRAMENTA) $(BIBLIOTECA) | 111 |
cobertura | — | 129 |
docs-gerar | — | 139 |
docs-check | — | 142 |
docs-test | — | 145 |
docs-build | docs-gerar docs-test | 148 |
limpar | — | 153 |
ajuda | — | 156 |
Workflows versionados
Documentação
Ver workflow
name: Documentação
# Gera a referência a partir do código em todos os PRs e publica pushes.
# O ramo da entrega está incluído para permitir a primeira publicação via Pages;
# depois do merge, main continua publicando automaticamente.
on:
push:
branches: [main, arena/37183924-basicgol]
paths:
- 'include/**'
- 'src/**'
- 'tools/**'
- 'tests/**'
- 'docs/**'
- 'website/**'
- 'README.md'
- 'llms.txt'
- 'Makefile'
- '.github/workflows/docs.yml'
pull_request:
paths:
- 'include/**'
- 'src/**'
- 'tools/**'
- 'tests/**'
- 'docs/**'
- 'website/**'
- 'README.md'
- 'llms.txt'
- 'Makefile'
- '.github/workflows/docs.yml'
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: github-pages
cancel-in-progress: false
jobs:
build:
name: Gerar e validar documentação
runs-on: ubuntu-latest
timeout-minutes: 25
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Python
uses: actions/setup-python@v5
with:
python-version: '3.11'
cache: pip
cache-dependency-path: tools/documentacao/requirements.txt
- name: Node
uses: actions/setup-node@v4
with:
node-version: '22'
cache: npm
cache-dependency-path: website/package-lock.json
- name: Instalar dependências Python
run: python -m pip install -r tools/documentacao/requirements.txt
- name: Instalar dependências Node
working-directory: website
run: npm ci --no-audit --no-fund
- name: Gerar inventário e páginas
env:
DOCS_COMMIT: ${{ github.sha }}
DOCS_REPOSITORY_URL: ${{ github.server_url }}/${{ github.repository }}
run: python tools/gerar_documentacao.py --strict
- name: Testar gerador
run: python -m unittest discover -s tests/documentacao -v
- name: Typecheck
working-directory: website
run: npm run typecheck
- name: Build Docusaurus
working-directory: website
env:
DOCS_URL: ${{ vars.DOCS_URL || 'https://havaianasdestruido.github.io' }}
DOCS_BASE_URL: ${{ vars.DOCS_BASE_URL || format('/{0}/', github.event.repository.name) }}
run: npm run build:only
- name: Verificar publicação do llms.txt
env:
DOCS_BASE_URL: ${{ vars.DOCS_BASE_URL || format('/{0}/', github.event.repository.name) }}
run: python tests/documentacao/check_llms_build.py
- name: Configurar Pages
if: github.event_name != 'pull_request'
uses: actions/configure-pages@v5
- name: Enviar artifact do Pages
if: github.event_name != 'pull_request'
uses: actions/upload-pages-artifact@v3
with:
path: website/build
deploy:
name: Publicar no GitHub Pages
if: github.event_name != 'pull_request'
needs: build
runs-on: ubuntu-latest
timeout-minutes: 10
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Publicar
id: deployment
uses: actions/deploy-pages@v4
MinGW-w64
.github/workflows/mingw-w64.yml
Ver workflow
name: MinGW-w64
on:
push:
pull_request:
workflow_dispatch:
permissions:
contents: read
concurrency:
group: mingw-w64-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
build:
name: ${{ matrix.msystem }}
runs-on: windows-latest
timeout-minutes: 30
strategy:
fail-fast: false
matrix:
include:
- msystem: UCRT64
package_arch: ucrt-x86_64
artifact: windows-x86_64-ucrt
- msystem: MINGW64
package_arch: x86_64
artifact: windows-x86_64-msvcrt
- msystem: MINGW32
package_arch: i686
artifact: windows-i686-msvcrt
defaults:
run:
shell: msys2 {0}
steps:
# Keep the Bash runners and golden output files LF-only on Windows.
- name: Configure Git line endings
shell: bash
run: git config --global core.autocrlf input
- uses: actions/checkout@v7
- name: Set up MinGW-w64
uses: msys2/setup-msys2@v2
with:
msystem: ${{ matrix.msystem }}
update: true
path-type: strict
install: >-
diffutils
make
mingw-w64-${{ matrix.package_arch }}-gcc
- name: Show toolchain versions
run: |
gcc --version
ar --version
make --version
- name: Build transpiler and static library
run: make all CC=gcc AR=ar
- name: Run language and library tests
run: |
if ! make test CC=gcc AR=ar > build/test.log 2>&1; then
cat build/test.log
grep -A8 'FALHA' build/test.log | head -60 | sed 's/^/::error::/'
tail -8 build/test.log | sed 's/^/::error::/'
exit 1
fi
cat build/test.log
- name: Build examples
run: make exemplos CC=gcc AR=ar
- name: Package Windows build
run: |
package="dist/basicgol-${{ matrix.artifact }}"
mkdir -p "$package"
cp -R include "$package/"
cp build/libbasicgol.a LICENSE README.md "$package/"
if [ -f build/basicgolc.exe ]; then
cp build/basicgolc.exe "$package/"
else
cp build/basicgolc "$package/basicgolc.exe"
fi
"$package/basicgolc.exe" --versao
- name: Upload Windows build
uses: actions/upload-artifact@v7
with:
name: basicgol-${{ matrix.artifact }}
path: dist/basicgol-${{ matrix.artifact }}/
if-no-files-found: error
retention-days: 14
msvc
Ver workflow
name: msvc
# Compila e testa o BASICGOL com o Microsoft Visual C++ (cl.exe), na raiz
# Windows deste projeto. Complementa o testes.yml (GCC/Clang em Linux):
# nenhuma fonte depende de extensão de GNU (D-15), e esta suíte prova isso.
#
# Particularidades do MSVC usadas aqui:
# /TC fontes sempre C, mesmo num projeto configurado como C++ (D-14);
# com /TC o cl trata TODOS os arquivos da linha de comando como
# fontes C — por isso o .lib vai DEPOIS de /link (vai ao linkador)
# /std:c11 cl.exe moderno (VS 2019 16.8+ / VS 2022) tem _Generic e
# _Static_assert; sem ele o cabeçalho recusa compilar
# /W4 /WX equivalente aproximado de -Wall -Wextra -Werror do testes.yml
# lib.exe no lugar do `ar rcs` do Makefile; empacota build/libbasicgol.lib
# -lm desnecessário na UCRT (o math entra na biblioteca padrão)
# _CRT_* silenciam C4996 (o CRT pede scanf_s/strncpy_s; o projeto usa
# as funções C11 padrão deliberadamente)
#
# Os exemplos e os testes dourados rodam sob Git Bash (shell: bash), com as
# comparações de bytes normalizando \r — o CRT escreve \n como \r\n no modo
# texto. O runner dos exemplos é tests/run_msvc.sh; lá os exemplos compilam com
# /W3 (código didático; a saída dourada é o que importa), enquanto o núcleo
# produto (ferramenta, biblioteca, testes) usa /W4 /WX.
on:
push:
pull_request:
jobs:
construir:
runs-on: windows-latest
steps:
- uses: actions/checkout@v4
# Coloca cl.exe/lib.exe no PATH com ambiente x64. É a forma padrão de
# ativar a toolchain em runners Windows; o Visual Studio já vem na
# imagem. Se preferir não usar a action, chame VsDevCmd.bat do VS mais
# recente dentro de um único passo cmd — o resultado é o mesmo.
- name: ativar toolchain MSVC (x64)
uses: ilammy/msvc-dev-cmd@v1
with:
arch: x64
- name: basicgolc (transpilador M1)
shell: cmd
run: |
if not exist build mkdir build
cl /nologo /TC /std:c11 /W4 /WX /D_CRT_SECURE_NO_WARNINGS /D_CRT_NONSTDC_NO_WARNINGS tools\basicgolc.c /Fo:build\basicgolc.obj /Fe:build\basicgolc.exe > build\basicgolc.log 2>&1
if errorlevel 1 (
for /f "usebackq delims=" %%i in ("build\basicgolc.log") do echo ::error::%%i
exit /b 2
)
- name: biblioteca estatica (libbasicgol.lib)
shell: cmd
run: |
if not exist build\biblioteca mkdir build\biblioteca
for %%f in (src\biblioteca\*.c) do (
cl /nologo /TC /std:c11 /W4 /WX /D_CRT_SECURE_NO_WARNINGS /D_CRT_NONSTDC_NO_WARNINGS /I include /c %%f /Fo:build\biblioteca\ > build\biblioteca\cl.log 2>&1
if errorlevel 1 (
for /f "usebackq delims=" %%i in ("build\biblioteca\cl.log") do echo ::error::%%i
exit /b 2
)
)
lib /nologo /OUT:build\libbasicgol.lib build\biblioteca\*.obj
- name: testes unitarios da biblioteca (test_biblioteca)
shell: cmd
run: |
cl /nologo /TC /std:c11 /W4 /WX /D_CRT_SECURE_NO_WARNINGS /D_CRT_NONSTDC_NO_WARNINGS /I include tests\test_biblioteca.c /Fo:build\test-biblioteca.obj /Fe:build\test-biblioteca.exe /link build\libbasicgol.lib > build\test_biblioteca.log 2>&1
if errorlevel 1 (
for /f "usebackq delims=" %%i in ("build\test_biblioteca.log") do echo ::error::%%i
exit /b 2
)
- name: rodar testes unitarios (wrappers, fatal, limites)
shell: bash
run: ./tests/run_biblioteca.sh build/test-biblioteca.exe
- name: exemplos com saida dourada (M0 e M1)
shell: bash
run: ./tests/run_msvc.sh
- name: diagnostico (apenas em falha)
if: failure()
continue-on-error: true
shell: bash
run: |
where cl || true
cl 2>&1 | head -2 || true
git log --oneline -1
testes
Ver workflow
name: testes
# Fase 6 — o CI é a execução "de verdade" da matriz: aqui GCC e Clang são
# compiladores reais (no ambiente de desenvolvimento da Fase 6 só havia GCC e
# o frontend Clang empacotado no zig; ver docs/12-relatorio-fase-6.md).
#
# suite — linguagem + biblioteca, GCC e Clang, C11 e C17
# sanitizers — a mesma suíte sob ASan+UBSan, GCC e Clang
# portabilidade — matriz, avisos, multi-UO, C++, sanitizers e fuzz
# msvc — avaliação de compilação com cl.exe (não bloqueante: o
# relatório da Fase 6 não executou MSVC; ver docs/11)
# cobertura — a matriz de rastreabilidade está atualizada
on:
push:
pull_request:
jobs:
suite:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
cc: [gcc, clang]
std: [c11, c17]
steps:
- uses: actions/checkout@v4
- name: versão do compilador
run: ${{ matrix.cc }} --version | head -1
- name: suíte completa (M0 + M1 + biblioteca padrão)
env:
CC: ${{ matrix.cc }}
T_CFLAGS: -std=${{ matrix.std }} -Wall -Wextra -Wformat=2 -Wvla -Werror
run: make test CC=${{ matrix.cc }}
- name: exemplos com saída dourada
run: make exemplos CC=${{ matrix.cc }}
- name: cabeçalho em C11/C17 com -pedantic
run: |
printf '#include <basicgol.h>\nINICIO\n ESCREVAL("x");\nFIM\n' > /tmp/h.c
${{ matrix.cc }} -std=${{ matrix.std }} -pedantic -Wall -Wextra \
-Wformat=2 -Wvla -Werror -I include /tmp/h.c build/libbasicgol.a -lm -o /tmp/h
test "$(/tmp/h)" = x
- name: diagnóstico (apenas em falha)
if: failure()
continue-on-error: true
env:
CC: ${{ matrix.cc }}
T_CFLAGS: -std=${{ matrix.std }} -Wall -Wextra -Wformat=2 -Wvla -Werror
run: |
./tests/run.sh -v > /tmp/log 2>&1 || true
grep -A1 "FALHA" /tmp/log | head -60 | sed 's/^/::error::/'
tail -3 /tmp/log | sed 's/^/::error::/'
sanitizers:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
cc: [gcc, clang]
steps:
- uses: actions/checkout@v4
- name: suíte completa sob ASan + UBSan
env:
CC: ${{ matrix.cc }}
ASAN_OPTIONS: detect_leaks=1
UBSAN_OPTIONS: print_stacktrace=1
run: make test-sanitize CC=${{ matrix.cc }}
portabilidade:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
cc: [gcc, clang]
steps:
- uses: actions/checkout@v4
- name: compilador e versões
run: |
${{ matrix.cc }} --version | head -1
g++ --version | head -1
- name: matriz de portabilidade
env:
CC: ${{ matrix.cc }}
run: make test-portabilidade CC=${{ matrix.cc }} T_CC_ALT=${{ matrix.cc == 'gcc' && 'clang' || 'gcc' }}
- name: fuzz determinístico do transpilador
run: make fuzz CC=${{ matrix.cc }}
- name: artefato — relatório da matriz
if: always()
uses: actions/upload-artifact@v4
with:
name: matriz-${{ matrix.cc }}
path: build/relatorio/portabilidade.tsv
if-no-files-found: ignore
msvc:
# Avaliação, não certificação: este job compila com cl.exe e mostra o
# resultado. Enquanto não houver um resultado verde documentado em
# docs/11-matriz-compatibilidade.md, ele NÃO bloqueia o merge.
runs-on: windows-latest
continue-on-error: true
steps:
- uses: actions/checkout@v4
- uses: ilammy/msvc-dev-cmd@v1
- name: versão do cl
shell: cmd
run: cl 2>&1 | findstr /C:"Version"
- name: biblioteca + ola_mundo em /std:c11 /W4
shell: cmd
run: |
cl /nologo /std:c11 /W4 /Iinclude /Fe:ola.exe ^
docs\exemplos\ola_mundo.c ^
src\biblioteca\consola.c src\biblioteca\matematica.c ^
src\biblioteca\texto.c src\biblioteca\caractere.c ^
src\biblioteca\utilidades.c
- name: transpilador em /std:c11 /W4
shell: cmd
run: cl /nologo /std:c11 /W4 /Fe:basicgolc.exe tools\basicgolc.c
- name: executar o exemplo
shell: cmd
run: ola.exe
- name: caminho M1 no Windows (transpila e compila o C gerado)
shell: cmd
run: |
basicgolc.exe docs\exemplos\controle_lacos.c -o gerado.c
cl /nologo /std:c11 /W4 /Iinclude /Fe:gerado.exe gerado.c ^
src\biblioteca\consola.c src\biblioteca\matematica.c ^
src\biblioteca\texto.c src\biblioteca\caractere.c ^
src\biblioteca\utilidades.c
gerado.exe
cobertura:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: a matriz de cobertura está atualizada
run: |
make cobertura
git diff --exit-code tests/COBERTURA.md
Gerar este site
python3 -m venv .venv
.venv/bin/python -m pip install -r tools/documentacao/requirements.txt
cd website
npm ci
npm run build
No Windows, ative o ambiente com .venv\Scripts\activate e use python em vez de .venv/bin/python. Veja publicação e manutenção para GitHub Pages e evolução automática.
Perguntas frequentes
Perguntas frequentes sobre build local, alvos do Makefile e integração contínua.
Qual é o primeiro comando para construir tudo?
make produz o transpilador e a biblioteca em build/. O Makefile pressupõe ambiente Unix-like; no Windows o projeto usa os workflows MSYS2/MinGW e MSVC documentados no repositório.
make
ls build/
Quais alvos verificam a linguagem e a biblioteca?
Cada alvo cobre uma camada: casos dourados, suíte unitária, matriz de portabilidade, sanitizers e fuzz de mutação do transpilador.
make test
make test-biblioteca
make test-portabilidade
make test-sanitize
make fuzz
Como limpar artefatos sem apagar o fonte?
O alvo de limpeza remove a árvore build/; a lista completa de alvos está na tabela acima, extraída do próprio Makefile.
make limpar # confira o nome exato na tabela acima antes de usar
O que a CI executa além dos testes locais?
A matriz de compiladores × padrões, sanitizers, cobertura, avaliação MSVC e o workflow nativo MinGW-w64. A página de portabilidade explica quais estados significam executado, compilado, avaliado e não testado.
Este site é construído no mesmo pipeline?
Sim. .github/workflows/docs.yml instala Python e Node, gera o inventário, roda os testes do gerador, compila o Docusaurus e publica via GitHub Pages.
cd website
npm run build
npm run serve