Build, execução e depuração¶

O ChrisOS possui vários caminhos de build e execução. Selecionar o caminho mais estreito que exercita o subsistema alterado reduz o tempo de iteração e torna as falhas mais fáceis de classificar.

Artefatos principais¶

Na raiz do repositório:

make

O alvo padrão produz build/os.iso. O kernel pode ser compilado isoladamente:

make kernel

A imagem persistente do workspace ChrisFS é criada com:

make disk.img

Esses comandos provam coisas diferentes. Compilar o kernel não prova criação correta da ISO; produzir a ISO não prova boot; um boot não prova um caminho específico de dispositivo ou filesystem.

QEMU interativo¶

O target padrão é:

make run

Na revisão analisada, ele prepara os artefatos necessários, inicia QEMU x86-64 com o conjunto normal de dispositivos virtuais, envia a serial do guest para o terminal e solicita KVM.

Se make run falhar antes de aparecer qualquer saída serial do ChrisOS, verifique primeiro se o QEMU conseguiu iniciar. Falta de acesso a KVM, backend de display indisponível, opção inválida do QEMU ou artefato ausente são falhas de host.

Falha do guest só começa depois que a máquina virtual está realmente executando código do ChrisOS.

Execução headless portátil¶

Para integração reproduzível, prefira gates mantidos pelo projeto. O smoke test comum é:

make test-qemu-ata

Esse gate utiliza TCG, grava serial em build/qemu-test.txt e verifica marcadores explícitos.

Conjuntos mais amplos:

make host-gates
make qemu-gates
make full-gates

Durante desenvolvimento, execute primeiro o teste mais específico. A suíte inteira é confirmação posterior, não o melhor instrumento para localizar um defeito local.

Gates por dispositivo¶

scripts/qemu.mk define caminhos separados para dispositivos e configurações de boot. Exemplos:

make test-qemu-ahci
make test-qemu-nvme
make test-qemu-vblk
make test-qemu-usb
make test-qemu-gpu
make test-qemu-xhci
make test-qemu-safe
make test-qemu-install

Esses resultados são evidência em modelos QEMU; não provam compatibilidade com hardware físico arbitrário.

ChrisVM¶

O caminho de emulação mantido pelo próprio projeto possui targets separados:

make chrisvm
make chrisvm-test

Falhas ChrisVM devem ser separadas conceitualmente das falhas QEMU. Uma alteração pode quebrar o emulador sem quebrar o guest no QEMU, ou o ChrisVM pode expor uma suposição do guest que um modelo QEMU tolera.

RISC-V¶

O bring-up RISC-V é:

make riscv
make run-riscv

Esse caminho não representa paridade de funcionalidades com x86-64. Seus resultados devem ser descritos como evidência específica dessa arquitetura.

Depuração orientada pela serial¶

A serial é a interface mais confiável para diagnóstico inicial de kernel e dispositivos. make run envia a serial ao terminal; os gates headless gravam logs determinísticos.

Quando um gate falhar:

1. preserve o primeiro log com falha;
2. identifique o último marcador bem-sucedido;
3. repita o gate mais estreito;
4. classifique a falha como host ou guest;
5. instrumente apenas o caminho relevante;
6. remova debug temporário ou transforme-o em logging intencional antes do merge.

Não substitua uma verificação determinística por observação visual do desktop.

Estado do GDB¶

O repositório não define hoje GDB como target de validação de primeira classe. QEMU pode expor genericamente um stub remoto de GDB e isso pode ser útil localmente, mas um comando QEMU ad-hoc continua sendo uma técnica de depuração, não um resultado de teste mantido pelo projeto.

Se um workflow GDB canônico for adicionado, ele deve ganhar target reproduzível e documentação operacional próxima ao build.

Safe mode¶

A suíte QEMU possui caminho de safe mode. Ele é útil quando subsistemas opcionais escondem um problema de boot mais baixo.

Se a configuração normal falhar e safe mode funcionar, compare os caminhos de inicialização desativados por safe mode antes de reabrir hipóteses sobre reset, bootloader ou memória básica.

VirGL¶

O gate é:

make test-qemu-virgl

Ele verifica capacidades do host antes do guest e pode retornar skip se QEMU ou stack gráfico não puderem fornecer o ambiente.

Skip não é pass.

Build limpo e incremental¶

Quando artefatos antigos forem plausíveis:

make clean
make

Porém builds limpos não devem esconder dependências incorretas no Makefile. Se o build incremental falha repetidamente em reconstruir algo que deveria mudar, o grafo de dependências precisa ser corrigido.

Disciplina com imagens de disco¶

build/disk.img e imagens temporárias dos gates são artefatos descartáveis. Instalação em disco físico é outro fluxo e não deve ser misturada com debug normal.

Pare o QEMU antes de modificar offline uma imagem ChrisFS.

Classificação de falhas¶

Essa separação evita depurar código do guest para um problema que ocorreu antes de o guest executar.