pf-linux-port/docs/pt-BR/build.md

Pipeline de build em detalhe

English: docs/en/build.md. Receita rápida: install.md. Esta página explica o que cada etapa faz e o que já foi realmente exercitado.

Tudo abaixo roda no host de build (o laptop); a bancada de VMs (host separado, "deb") só recebe artefatos — ver vm-lab.md.

0. Pré-requisitos

De docs/pt-BR/install.md: gcc ≥ 15, GNU make, bison (flex não é necessário — o parse.y do OpenBSD traz um yylex escrito à mão), bc, rsync, glibc-static para o pfctl estático, root para insmod. A árvore do kernel é esperada em ../linux-7.3.4 (troque com KERNELDIR=; o Makefile raiz usa $(HOME)/lab/linux_kernel/linux-7.3.4).

1. Baixar + verificar as fontes do OpenBSD — scripts/fetch-sources.sh

• Baixa sys.tar.gz e src.tar.gz do mirror primário https://openbsd.c3sl.ufpr.br/pub/OpenBSD/8.0/, com fallback para cdn.openbsd.org.
• Confere o sha256 contra os valores de VERSIONS (sys: 964b1aed…, src: 9984c74f…); tarball já em cache com hash correto é pulado.
• Destino: _vendor/openbsd/ (fora do git).

2. Vendorize — scripts/vendorize.sh

Extrai só os arquivos que o port consome para _vendor/upstream/ (fora do git): a lista sys/net/pf*.c|h, ifq/hfsc/fq_codel/ip_pflog/ ip_divert, radix/rtable/toeplitz, crypto/{md5,sha2,siphash}, sys/sys/*.h e sbin/pfctl/* + headers (arrays SYS_K/SRC_K). Em seguida registra o tag $OpenBSD: …$ de cada arquivo em _vendor/upstream/IDS.txt — a base forense de toda linha portada e de futuros rebases.

3. Staging para o port — scripts/stage-port.sh (porting determinístico)

O stage-port.sh transforma os arquivos upstream pristinos nos arquivos em module/:

1. todo #include é substituído por pfk.h + os headers pfvar staged (os ramos de kernel são selecionados com -D_KERNEL=1);
2. o programa de renomeação compartilhado (pf_sed) resolve colisões de nomes BSD↔Linux (struct ip → struct pf_ip, ifnet → pfk_ifnet, ip_output → pfk_ip_output, atribuições a sa_len removidas, …);
3. cada execução é anexada a docs/porting-notes.md — esse arquivo é o log de staging, não prosa.

Os arquivos portados são então commitados e editados à mão na árvore; o re-staging serve só para perícia (stage-port.sh --diff <arquivo> compara a nossa cópia com o texto upstream pristino). Radix/rtable/siphash/toeplitz ficam de fora do staging automático de propósito (portados à mão).

4. Kernel — scripts/build-kernel.sh (+ kernel-config.sh)

• kernel-config.sh: parte de defconfig quando não há .config e então ajusta (idempotente, via scripts/config + make olddefconfig): VIRTIO_BLK/PCI/NET=y, EXT4_FS=y, NETFILTER=y, NETFILTER_ADVANCED, NET_SCHED=y, INET=y, IPV6=y, SERIAL_8250(+CONSOLE)=y — ou seja, tudo que o boot direto da VM pf0 precisa sem initrd. kernel-config.sh test habilita também DEBUG_INFO + DEBUG_KMEMLEAK para builds de soak.
• build-kernel.sh: make -j(nproc-2) bzImage modules_prepare, garante que Module.symvers exista (copia vmlinux.symvers — o kbuild não escreve o primeiro) e que scripts/module.lds exista; depois deposita os artefatos de boot em out/: linux-<ver>-bzImage, System.map, .config, kernelversion, bzImage.sha256. Termina com KERNEL_BUILD_OK <kernelrelease>.
• Hoje não há patch de core: patches/kernel/ não tem nenhum 000N-*.patch (ver patches.md).

5. Módulo — scripts/build-module.sh

make -C "$KERNELDIR" M=module → module/pf.ko (um único módulo: a interface BSD ifq/pfq mora dentro dele, não é um qdisc tc separado). O script prepara sozinho Module.symvers / modules_prepare. Lista de objetos (module/Makefile): engine portado (pf.c, pf_ioctl.c, pf_norm.c, pf_if.c, pf_lb.c, pf_ruleset.c, pf_table.c, pf_osfp.c, pf_syncookies.c, divert_sock.c, pfk_pflog.c, hfsc.c, fq_codel.c) + camada de compat (shim mbuf, glue de kernel, if/ip4/ip6/pcb/xmit/ifq, crypto, radix, subr_tree) + pfk_mod.c/pfk_hooks.c. As flags de compilação definem PFLINUX=1 e _KERNEL=1. Termina com MODULE_BUILD_OK.

insmod module/pf.ko cria /dev/pf (0600) e registra os hooks netfilter; o dmesg mostra linhas pfk: … (ver caveats.md para o que o caminho de dados faz).

6. Userland — make -C tools

Alvos (de tools/Makefile): pfctl, pdivert, pflogd, abitest, abi, test, clean.

• pfctl — as fontes do OpenBSD 8.0 compiladas contra os headers de ABI copiados; o resultado é um binário estático em tools/out/pfctl. Cada desvio do upstream está listado em tools/UPSTREAM.md (7 edições marcadas; o resto é o conjunto de headers/fontes de compat).
• abi — compila abitest (userland) e abitest-module (mesma tabela com os headers de compat de kernel), despeja as tabelas de tamanho/offset de cada struct e as compara com diff; divergência = ABI de ioctl quebrada. out/abi-*.tbl são as entradas de referência.
• test — checagens de parse offline: roda pfctl -n -f sobre tools/tests/*.conf (básico / traduções / filas+scrub / anchor / negativa broken.conf). É userland puro; não precisa de /dev/pf.
• pdivert — o relay de divert, compilado a partir de tools/pdivert/. Ele fala com a família de sockets AF_DIVERT que o módulo registra em runtime (socket(PF_DIVERT=32, SOCK_RAW, IPPROTO_DIVERT=254)); o gate 11-divert.sh prova a ida e a volta.
• pflogd — lê /dev/pflog e escreve um pcap DLT_PFLOG cujo layout de registro é byte a byte compatível com o pflog(4) do OpenBSD; gate 12-pflog.sh.

7. Screencasts — scripts/screencast/build-all.sh

Não faz parte do build do kernel, mas faz parte da entrega. O pipeline:

Etapa	Script	O que faz
texto da narração	make_narration.py	escreve scripts/screencast/narration/<fase>.{en,pt}.json (um segmento por batida da sessão)
voz	make_audio.py	TTS do MiniMax, um MP3 por segmento, voz feminina por idioma
sessão	record.py	sessão SSH real no lab: comandos digitados tecla a tecla, capturada como asciicast v2
vídeo	render_video.py	reproduz a captura por um emulador de terminal, desenha o diagrama do lab, queima as legendas
montagem	assemble.py	mixa a narração na linha do tempo
filme completo	join.py	emenda as fases com crossfade sobre cartões de capítulo

make screencast (ou o script) roda tudo; precisa de MINIMAX_API_KEY e do lab no ar. Detalhes: screencast.md.

8. Makefile raiz

make module | tools | kernel | vm | vm-destroy | test | screencast | docs | clean — wrappers finos sobre os scripts acima. make test roda a suíte em VM (vm-lab.md); make screencast renderiza os vídeos; make docs apenas lista o conjunto bilíngue.

O que já foi exercitado vs. não

• As etapas 1–6 foram rodadas repetidamente no host de build (há artefatos na árvore: out/, module/pf.ko, tools/out/{pfctl,pdivert,pflogd}), e os scripts acima foram verificados linha a linha para este documento.
• A etapa 7 (os screencasts) foi rodada de ponta a ponta para as sete fases nos dois idiomas; os vídeos estão em out/screencast/{en,pt}/.
• Uma execução de ponta a ponta a partir de clone limpo (quickstart-check.sh, tarefa T19 do plano) ainda não foi feita; trate a sequência exata do install.md como "conforme projetada e conforme o último estado por milestone", não como verificada em CI.