Build, run and debug¶

ChrisOS has multiple build and execution paths. Selecting the narrowest path that exercises the modified subsystem reduces iteration time and makes failures easier to classify.

Core artifacts¶

From the repository root:

make

The default target produces build/os.iso. The kernel can be built separately:

make kernel

The persistent ChrisFS workspace disk is:

make disk.img

These commands establish different facts. Kernel compilation does not prove ISO construction; ISO construction does not prove boot; a boot does not prove a specific device or filesystem path.

Interactive QEMU¶

The standard interactive target is:

make run

At the reviewed revision, this target prepares the required artifacts, starts x86-64 QEMU with the project's normal virtual-device set, routes the guest serial stream to the terminal and requests KVM acceleration.

If make run fails before any ChrisOS serial output appears, first determine whether QEMU started successfully. Missing KVM access, an unavailable display backend, an invalid host QEMU option or an absent artifact is a host-side failure.

A guest failure begins only after the virtual machine is actually executing ChrisOS.

Portable headless execution¶

For reproducible integration work, prefer maintained gates. The common smoke path is:

make test-qemu-ata

The gate uses TCG, writes serial output to build/qemu-test.txt and checks explicit progress markers.

Broader sets are:

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

Run the narrow test first. A large suite is confirmation after the relevant invariant is stable, not the best first diagnostic.

Device-specific QEMU gates¶

scripts/qemu.mk defines separate paths for major device and boot configurations. Examples include:

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

These gates provide QEMU-model evidence. They do not prove physical-device compatibility.

ChrisVM¶

The project-owned emulation path has separate targets:

make chrisvm
make chrisvm-test

Keep ChrisVM failures conceptually separate from QEMU failures. A change can break the emulator without breaking the guest under QEMU, or ChrisVM can expose a guest assumption that a QEMU model happens to tolerate.

RISC-V bring-up¶

The RISC-V path is:

make riscv
make run-riscv

This is a bring-up target, not feature parity with the x86-64 system. Its results should be described as architecture-specific evidence.

Serial-first debugging¶

The serial stream is the primary early diagnostic path. Interactive make run sends it to the terminal; headless gates capture it into a build log.

When a gate fails:

1. preserve the first failing log;
2. identify the last successful marker;
3. rerun the narrowest gate;
4. classify the failure as host-side or guest-side;
5. instrument the smallest relevant path;
6. turn useful temporary diagnostics into intentional logging or remove them before merge.

Avoid replacing a deterministic check with visual observation of the desktop.

GDB status¶

The repository does not currently define GDB as a maintained first-class validation target. QEMU can expose a remote GDB stub in generic configurations, and a contributor may use that facility locally, but an ad-hoc QEMU command line is a debugging technique rather than a project test result.

Do not report a local GDB session as equivalent to a maintained gate. If a stable project-level GDB workflow is added later, it should have a reproducible target and documentation close to the build system.

Safe mode¶

The QEMU test suite includes a safe-mode image path. Safe mode is useful when optional subsystems obscure a lower-level boot problem.

If a normal configuration fails while the safe-mode gate succeeds, compare the initialization paths that safe mode disables instead of reopening reset, bootloader and basic memory assumptions from scratch.

VirGL¶

The graphics integration gate is:

make test-qemu-virgl

It first checks host capabilities and may skip when the QEMU binary or host display/GL stack cannot provide the required environment.

Treat outcomes distinctly:

A skip is not a pass.

Clean versus incremental builds¶

Generated artifacts can make a failure look inconsistent with source changes. When stale output is plausible:

make clean
make

However, clean builds should not hide missing dependency declarations. If an incremental build fails to rebuild a file that should have changed, the build graph itself needs correction.

Disk-image discipline¶

build/disk.img and the temporary images created by QEMU gates are disposable developer artifacts. Physical-disk installation is a separate operation and should never be substituted casually for ordinary build testing.

Stop QEMU before performing offline modifications to the workspace image. Use the repository-provided host or live transfer mechanisms according to the current build guide.

Failure classification¶

This classification avoids a common systems-development error: debugging guest code for a problem that happened before the guest executed.