Contributing to Lych

Thank you for considering contributing to Lych OS!

Getting Started

Lych is a hobby operating system for ARM64 written in Rust. Before contributing, please familiarize yourself with the project by reading the About page and the README.

All contributors are expected to follow our Code of Conduct.

Prerequisites

To build and test Lych locally, you'll need:

  • Rust toolchain — As pinned in rust-toolchain.toml, with rust-src component and aarch64-unknown-none target
  • QEMU — AArch64 system emulator (qemu-system-aarch64)
  • GDB — gdb-multiarch for debugging

Install Rust prerequisites:

rustup component add rust-src
rustup target add aarch64-unknown-none

Install QEMU and GDB (example for Debian/Ubuntu):

apt install qemu-system-arm gdb-multiarch

Windows: Use .\scripts\lych.ps1 from PowerShell or ./scripts/lych from Git Bash.

Development Workflow

  1. Fork the repository and create a feature branch
  2. Build the kernel: ./scripts/lych build
  3. Run in QEMU: ./scripts/lych run
  4. Debug (optional): ./scripts/lych debug + ./scripts/lych gdb
  5. Format code: ./scripts/lych fmt
  6. Check formatting: ./scripts/lych fmt-check
  7. Submit a pull request with a clear description

Code Style

  • Follow Rust standard style (rustfmt)
  • Run ./scripts/lych fmt-check before committing
  • Write clear, concise commit messages
  • Document new public APIs with doc comments
  • Keep functions small and focused
  • Use meaningful names — avoid abbreviations

Repository Structure

Path Purpose
arch/arm64/Startup assembly and exception-entry stubs
boot/Kernel linker script
kernel/The kernel crate (no_std, no_main)
kernel/src/arch/CPU and exception-handling primitives
kernel/src/drivers/Device drivers (currently PL011 UART)
kernel/src/memory/Memory management (frame allocator, page tables, heap)
scripts/Build, run, and debug entry points
docs/Development notes

Testing

There is no formal test suite yet. Verify changes by:

  • Building successfully: ./scripts/lych build
  • Running in QEMU: ./scripts/lych run (should show kernel boot output)
  • Checking formatting: ./scripts/lych fmt-check

Pull Request Process

  • Ensure the build passes and formatting is correct
  • Write a clear PR description explaining the change and why
  • Reference any related issues
  • Keep PRs focused — one logical change per PR
  • Be responsive to review feedback

Roadmap Alignment

Contributions should generally align with the current development phase. See the Roadmap for the current focus areas. Before starting significant work, consider opening an issue to discuss the approach.

Reporting Issues

Use GitHub Issues for:

  • Bug reports (include build logs, QEMU output, steps to reproduce)
  • Feature requests (explain the use case)
  • Documentation improvements

Security Issues

Please report security vulnerabilities privately via email rather than opening a public issue. See our Security Policy.