# 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

```bash
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.

```bash
./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).

```bash
./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.

```bash
./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).

```bash
./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).

```bash
./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.

```bash
./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)
```bash
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
```bash
./uos-check.sh lint          # Check for style issues
./uos-check.sh build-core    # Verify core components compile
```

### After Major Changes
```bash
./uos-check.sh test          # Full build + boot tests
```

### Quick Verification
```bash
./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
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`