# Contributing to UniversalisOS

Thank you for your interest in contributing. This guide covers build prerequisites, code conventions, testing requirements, and the PR process.

## Build Prerequisites

### Kernel (C++, freestanding)

| Architecture | Toolchain | QEMU Package |
|-------------|-----------|--------------|
| ARMv7 | `arm-none-eabi-gcc` | `qemu-system-arm` |
| AArch64 | `aarch64-linux-gnu-gcc` | `qemu-system-aarch64` |
| RISC-V | `riscv64-linux-gnu-gcc` | `qemu-system-riscv64` |

Install on Debian/Ubuntu:
```bash
sudo apt install gcc-arm-none-eabi qemu-system-arm
sudo apt install gcc-aarch64-linux-gnu qemu-system-aarch64
sudo apt install gcc-riscv64-linux-gnu qemu-system-riscv64
```

### Mycelium Toolchain (Rust)

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

### Coverage & Package Tools (Python)

- Python 3.11 or later
- No external dependencies (stdlib only)

### VS Code Extension (optional)

```bash
cd mycelium-tfw-extension
npm install
```

## Code Style

### Naming Conventions

- **Prefix**: Use `uos_` for all new APIs. Do **not** use PikeOS prefixes (`p4_`, `UOS_PART_`, `P4_`).
- **Constants**: `UOS_HV_*` (hypervisor ABI), `UOS_SC_*` (system calls), `PV_SVC_*` (ARMv7 PV).
- **Files**: `snake_case.cpp`, `snake_case.h`.

### Language Rules

- **Freestanding C++**: No exceptions (`-fno-exceptions`), no RTTI (`-fno-rtti`).
- **No dynamic allocation**: Static/compile-time only in the kernel.
- **No standard library**: The kernel is freestanding; use `__aeabi_*` helpers when needed.
- **No comments** unless the *why* is non-obvious (hidden constraint, subtle invariant, bug workaround).
- **Compiler flags**: `-Wall -Wextra -ffreestanding -O2 -fno-tree-vectorize -g`.

### Header Guards

Use `#pragma once` or `#ifndef UOS_<MODULE>_H` / `#define UOS_<MODULE>_H`.

## Testing Requirements

All tests must pass before submitting a PR.

### Kernel Tests

```bash
cd kernel

# Build all three architectures
make ARCH=armv7 PLATFORM=qemu-arm-virt
make ARCH=aarch64 PLATFORM=qemu-aarch64-virt
make ARCH=riscv PLATFORM=polarfire
```

Each build must complete with zero errors and zero warnings.

### Mycelium Tests

```bash
cd /path/to/mycelium
cargo test
```

Currently 86 tests passing.

### uos-cover Tests

```bash
cd tools/uos-cover
python3 -m pytest test/
```

Currently 87 tests.

### uos-pkg Tests

```bash
cd tools/uos-pkg
python3 -m pytest test/
```

Currently 116 tests.

### Combined Python Tests

```bash
cd tools
python3 -m pytest uos-cover/test/ uos-pkg/test/
```

Currently 203+ tests.

## Pull Request Process

### 1. Branch

```bash
git checkout -b feature/your-feature-name
```

Use prefixes: `feature/`, `fix/`, `docs/`, `refactor/`.

### 2. Make Changes

Follow the code style rules above. Keep changes focused — one logical change per PR.

### 3. Build and Test

```bash
# Build the kernel for at least one architecture
cd kernel
make ARCH=armv7 PLATFORM=qemu-arm-virt

# Run Python tool tests
cd ../tools
python3 -m pytest uos-cover/test/ uos-pkg/test/

# Boot-test in QEMU (verify UART output)
qemu-system-arm -M virt -cpu cortex-a15 -m 512M \
  -nographic -kernel ../kernel/build/armv7/qemu-arm-virt/universalisos.elf
```

### 4. Commit

Write clear commit messages:
```
module: short description

Detailed explanation of what changed and why.
```

### 5. Push and Open PR

```bash
git push -u origin feature/your-feature-name
```

Open a pull request against `main`. Include:
- What the change does
- Which architectures were tested
- Test results (build output, test counts)

## Architecture Boundaries

When making changes, respect these boundaries:

| Directory | Scope |
|-----------|-------|
| `kernel/src/arch/armv7/` | ARMv7-specific (boot, exceptions, MMU, context switch) |
| `kernel/src/arch/aarch64/` | AArch64 EL2 hypervisor (self-contained) |
| `kernel/src/arch/riscv/` | RISC-V port (self-contained) |
| `kernel/src/core/` | Shared core (ARMv7 only; AArch64/RISC-V do not pull these) |
| `kernel/src/platform/drivers/` | Shared device drivers |
| `tools/` | Python toolchain (coverage, packaging) |

**Important**: A change to shared headers may break other architectures. Build and test all three when touching shared code.

## Verification Workflow

There is no linter or typechecker. Verification is:

1. `make ARCH=armv7 PLATFORM=qemu-arm-virt` — must compile clean
2. Boot in QEMU — must reach UART banner and complete demo sequence
3. Python tests — all must pass
4. If shared headers changed, verify AArch64 and RISC-V builds too

## License

By contributing, you agree that your contributions will be licensed under the MIT License.