Pular para o conteúdo principal

Build, comandos e integração contínua

Makefile vivo​

Targets extraídos diretamente do Makefile:

TargetDependênciasLinha
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
smoketest67
smoke-vtest-v69
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-builddocs-gerar docs-test148
limpar—153
ajuda—156

Workflows versionados​

Documentação​

.github/workflows/docs.yml

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​

.github/workflows/msvc.yml

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​

.github/workflows/testes.yml

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