189 lines
4.5 KiB
Markdown
189 lines
4.5 KiB
Markdown
# 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.
|