xtask API
English
cargo xtask is the host-side control surface for RustOS. The command enum is
defined in tools/xtask/src/cli.rs.
Commands
| Command | Purpose | Main output |
|---|---|---|
cargo xtask check | Validate layering, package manifests, targets, and workspace checks. | No image output. |
cargo xtask build | Full OS build and stage. | build/artifacts, build/image, registries. |
cargo xtask stage | Copy built artifacts and overlays into the boot image. | build/image. |
cargo xtask run | Run current staged image in QEMU. | QEMU session, logs/debugcon.log. |
cargo xtask debug | Run QEMU with GDB stub. | logs/rustos-debug.gdb. |
cargo xtask probe-display | Headless display probe/stress path. | Probe result and debug logs. |
cargo xtask qemu-scenarios | Run named QEMU regression scenarios. | QEMU logs and scenario result. |
cargo xtask selftest | Run host selftests for contracts and hardening helpers. | Cargo test output. |
cargo xtask fuzz-host | Run deterministic host parser fuzz smoke tests. | logs/fuzz-crash-*.bin on crash. |
cargo xtask clean | Remove cargo/build outputs. | Cleaned target/build dirs. |
cargo xtask targets | Install required Rust targets. | Rust target availability. |
cargo xtask build-efi | Build GRUB EFI boot manager only. Uses RUSTOS_GRUB_* when set, otherwise creates a local development key under build/dev-grub-gpg. | build/artifacts/EFI/BOOT/BOOTX64.EFI, build/artifacts/nucleus.elf.sig. |
cargo xtask build-kernel | Build Multiboot2 nucleus/kernel only. | build/artifacts/nucleus.elf. |
cargo xtask build-user | Build userspace packages. | service/app artifacts. |
cargo xtask build-console-demo | Build C demo/smoke programs. | app artifacts. |
cargo xtask build-driver-modules | Build bridge driver modules. | .ko artifacts. |
QEMU Options
cargo xtask run, debug, and probe-display accept shared options:
| Option | Meaning |
|---|---|
| `--profile <default | g14 |
--accel-profile kvm | Use KVM acceleration and host CPU profile. |
--usb-input | Attach qemu-xhci, usb-kbd, and usb-tablet. |
--no-network | Disable default usernet and virtio-net-pci. |
| `--debugcon <file | stdio |
| `--qemu-log <int | null>` |
--timeout <seconds> | Stop QEMU after a bounded run. No timeout is applied by default. |
--expect <marker> | Stop successfully once all repeated debugcon markers appear. |
--fault <location=action> | Add one validated fault-injection rule for this run. |
--summarize-log | Print high-signal debugcon markers after QEMU stops. |
--vfio-pci <BDF> | Attach a host vfio-pci device. |
--phoenix3-passthrough | Auto-detect and attach Phoenix3 GPU functions. |
--vfio-force | Allow devices driving active host display. |
Raw QEMU args go after --:
cargo xtask run -- --no-reboot
Bounded KVM no-opt debugging uses NVMe storage by default while AHCI boundary issues are isolated separately:
cargo xtask run --profile nvme --accel-profile kvm --usb-input --debugcon file --timeout 35 --summarize-log -- --no-reboot
Fault injection rules can come from config/rustos.toml or repeated
--fault arguments:
cargo xtask run --fault display.present=drop-every:10 --timeout 35 --summarize-log -- --no-reboot
Use cargo xtask qemu-scenarios --list to see the built-in scenario names.
When To Use Each Command
- Use
checkbefore commits that change dependencies, manifests, or layer boundaries. It also validates an existingbuild/artifacts/nucleus.elfwithgrub-file --is-x86-multiboot2when present. - Use
buildafter changing code or staged image content. The default build requires GRUB public/signing key environment variables. - Use
stageafter changing onlyassets/imageor package install metadata when artifacts are already built. - Use
runfor normal boot testing. - Use
debugwhen attaching GDB. - Use
probe-displayfor display, framebuffer, surface, or dirty-rect bugs.
한국어
cargo xtask는 RustOS의 host-side control surface입니다. command enum은
tools/xtask/src/cli.rs에 정의되어 있습니다.
Commands
| Command | Purpose | Main output |
|---|---|---|
cargo xtask check | layering, package manifest, target, workspace check를 검증합니다. | image output 없음 |
cargo xtask build | 전체 OS build와 stage를 수행합니다. | build/artifacts, build/image, registries |
cargo xtask stage | built artifact와 overlay를 boot image에 복사합니다. | build/image |
cargo xtask run | 현재 staged image를 QEMU에서 실행합니다. | QEMU session, logs/debugcon.log |
cargo xtask debug | GDB stub과 함께 QEMU를 실행합니다. | logs/rustos-debug.gdb |
cargo xtask probe-display | headless display probe/stress path를 실행합니다. | probe result와 debug logs |
cargo xtask qemu-scenarios | 이름이 있는 QEMU regression scenario를 실행합니다. | QEMU log와 scenario result |
cargo xtask selftest | contract와 hardening helper host selftest를 실행합니다. | Cargo test output |
cargo xtask fuzz-host | deterministic host parser fuzz smoke test를 실행합니다. | crash 시 logs/fuzz-crash-*.bin |
cargo xtask clean | cargo/build output을 지웁니다. | 정리된 target/build dirs |
cargo xtask targets | 필요한 Rust target을 설치합니다. | Rust target availability |
cargo xtask build-efi | GRUB EFI boot manager만 빌드합니다. RUSTOS_GRUB_* 값이 없으면 build/dev-grub-gpg 아래에 로컬 개발 키를 생성합니다. | build/artifacts/EFI/BOOT/BOOTX64.EFI, build/artifacts/nucleus.elf.sig |
cargo xtask build-kernel | Multiboot2 nucleus/kernel만 빌드합니다. | build/artifacts/nucleus.elf |
cargo xtask build-user | userspace package를 빌드합니다. | service/app artifacts |
cargo xtask build-console-demo | C demo/smoke program을 빌드합니다. | app artifacts |
cargo xtask build-driver-modules | bridge driver module을 빌드합니다. | .ko artifacts |
QEMU Options
cargo xtask run, debug, probe-display는 같은 option을 받습니다.
| Option | Meaning |
|---|---|
| `--profile <default | g14 |
--accel-profile kvm | KVM acceleration과 host CPU profile 사용 |
--usb-input | qemu-xhci, usb-kbd, usb-tablet attach |
--no-network | default usernet과 virtio-net-pci 비활성화 |
| `--debugcon <file | stdio |
| `--qemu-log <int | null>` |
--timeout <seconds> | 제한 시간 후 QEMU를 종료. 기본값은 timeout 없음 |
--expect <marker> | 반복 지정한 debugcon marker가 모두 나오면 성공으로 종료 |
--fault <location=action> | 이번 실행에만 validated fault-injection rule 추가 |
--summarize-log | QEMU 종료 후 high-signal debugcon marker 요약 출력 |
--vfio-pci <BDF> | host vfio-pci device attach |
--phoenix3-passthrough | Phoenix3 GPU function 자동 탐지/attach |
--vfio-force | active host display를 구동 중인 device도 허용 |
Raw QEMU arg는 -- 뒤에 둡니다.
cargo xtask run -- --no-reboot
KVM no-opt bounded debugging은 AHCI boundary issue를 별도로 격리하기 위해 우선 NVMe storage profile을 사용합니다.
cargo xtask run --profile nvme --accel-profile kvm --usb-input --debugcon file --timeout 35 --summarize-log -- --no-reboot
Fault injection rule은 config/rustos.toml에서 오거나 반복 지정한 --fault
argument에서 옵니다.
cargo xtask run --fault display.present=drop-every:10 --timeout 35 --summarize-log -- --no-reboot
내장 scenario 이름은 cargo xtask qemu-scenarios --list로 확인합니다.
언제 어떤 명령을 쓰는가
- dependency, manifest, layer boundary를 바꿨다면
check를 사용합니다. 기존build/artifacts/nucleus.elf가 있으면grub-file --is-x86-multiboot2도 검증합니다. - code 또는 staged image content를 바꿨다면
build를 사용합니다. 기본 build는 GRUB public/signing key 환경 변수가 필요합니다. - artifact가 이미 있고
assets/image또는 install metadata만 바꿨다면stage를 사용합니다. - 일반 boot test에는
run을 사용합니다. - GDB를 붙일 때는
debug를 사용합니다. - display, framebuffer, surface, dirty-rect bug에는
probe-display를 사용합니다.