universalisos/docs/CANONICAL_COMMANDS.md

UniversalisOS Canonical Test/Lint/Build Commands

Date: 2026-07-12
Status: ACTIVE
Location: kernel/uos-check.sh

---

Overview

The uos-check.sh script provides canonical commands for building, testing, and linting the UniversalisOS hypervisor. It replaces ad-hoc verification scripts with a standardized interface.

---

Quick Start

cd kernel/
./uos-check.sh help          # Show all commands
./uos-check.sh build-core    # Build core components (fast)
./uos-check.sh lint          # Run lint checks
./uos-check.sh test          # Build + boot smoke tests

---

Commands

build-core

Build core components only (for testing individual files). Fast, doesn't require full toolchain.

./uos-check.sh build-core

What it builds:

• src/core/abi/uos_posix_abi.cpp
• src/core/mm.cpp
• src/core/scheduler.cpp

Exit codes:

• 0 = all components compile
• 1 = one or more components failed

---

build-all

Build all architectures (armv7, aarch64, riscv).

./uos-check.sh build-all

Note: May fail due to pre-existing issues in:

• src/core/migration/device_state.cpp (unsupported architecture)
• src/core/adt/avl/adt_avl_common.c (type errors)

---

build-armv7 / build-aarch64 / build-riscv

Build a specific architecture.

./uos-check.sh build-armv7    # ARMv7 (qemu-arm-virt)
./uos-check.sh build-aarch64  # AArch64 (qemu-aarch64-virt)
./uos-check.sh build-riscv    # RISC-V (polarfire)

---

test

Run all tests (build + boot smoke tests).

./uos-check.sh test

What it does:

1. Builds all architectures
2. Runs boot smoke tests for each architecture
3. Verifies expected boot messages appear

Exit codes:

• 0 = all tests pass
• 1 = build failure
• 2 = test failure

---

lint

Run lint checks (format, static analysis).

./uos-check.sh lint

Checks:

• TODO/FIXME/HACK comments
• Trailing whitespace
• Tab characters
• Long lines (>120 chars)

Exit codes:

• 0 = lint checks completed (warnings allowed)
• 3 = lint failure

---

clean

Clean all build trees.

./uos-check.sh clean

---

Required Tools

ARMv7

• arm-none-eabi-gcc
• qemu-system-arm

AArch64

• aarch64-linux-gnu-gcc
• qemu-system-aarch64

RISC-V

• riscv64-unknown-elf-gcc
• qemu-system-riscv64

Installation (Fedora)

sudo dnf install gcc-arm-none-eabi gcc-aarch64-linux-gnu gcc-riscv64-unknown-elf \
    qemu-system-arm qemu-system-aarch64 qemu-system-riscv

---

Pre-existing Build Issues

The following issues are not caused by recent changes and are documented here for reference:

1. device_state.cpp — Unsupported Architecture

src/core/migration/device_state.cpp:111:2: error: #error "migration/device_state: unsupported architecture"

Impact: ARMv7 full build fails
Workaround: Use build-core for component testing

2. adt_avl_common.c — Type Errors

src/core/adt/avl/adt_avl_common.c:71:5: error: unknown type name 'uos_adt_avl_t'

Impact: AArch64 full build fails
Workaround: Compile individual files directly

3. Missing RISC-V Toolchain

riscv64-unknown-elf-gcc: command not found

Impact: RISC-V builds fail
Workaround: Install toolchain or skip RISC-V builds

---

Integration with Development Workflow

Before Committing

./uos-check.sh lint          # Check for style issues
./uos-check.sh build-core    # Verify core components compile

After Major Changes

./uos-check.sh test          # Full build + boot tests

Quick Verification

./uos-check.sh build-core    # Fast component check

---

Ad-hoc Verification Scripts

For targeted verification of specific changes, use ad-hoc scripts in /tmp/hermes-verify-*.sh. These are temporary and should be cleaned up after use.

Example:

bash /tmp/hermes-verify-t812g.sh    # Verify T8-1.2g changes

---

Future Improvements

• Add unit test framework
• Add code coverage reporting
• Add static analysis (clang-tidy, cppcheck)
• Add format checking (clang-format)
• Fix pre-existing build issues
• Add CI/CD integration

---

References

• Script: kernel/uos-check.sh
• Build System: kernel/Makefile
• Documentation: kernel/README.md
• AGENTS.md: universalisos/AGENTS.md