# Lenix
Lenix is a freestanding C microkernel with a Unix-like userland. The project
targets POSIX.1-2017 / UNIX V7 semantics, with x86_64 QEMU as the reference
development platform and an arm64 port in progress.
Lenix is under active development. It is useful for kernel, IPC, filesystem,
driver, runtime, and operating-system research, but it is not ready for
production use.
## Contents
- [Quick start](#quick-start)
- [Host setup](#host-setup)
- [Toolchain](#toolchain)
- [Building](#building)
- [Running in QEMU](#running-in-qemu)
- [Testing](#testing)
- [Architecture](#architecture)
- [Repository layout](#repository-layout)
- [Documentation](#documentation)
- [Known limitations](#known-limitations)
## Quick start
Ubuntu 26.04 LTS on amd64 is the supported build and QEMU test host. From the
repository root:
```bash
sudo ./setup.sh
sudo ./build-toolchain.sh
./rebuild.sh
make run-uefi
```
`setup.sh` installs the host packages. `build-toolchain.sh` downloads the
pinned LLVM 21.1.8 source, builds the Mercuron cross-toolchain, and installs it
under `/opt/llvm-mercuron`.
The LLVM build is large and can take some time. Run it once per pinned
toolchain version, not before every Lenix build.
## Host setup
Run the host setup script as root on a clean Ubuntu 26.04 amd64 installation:
```bash
sudo ./setup.sh
```
The script installs the compilers, build tools, GRUB utilities, OVMF firmware,
and QEMU packages used by the x86_64 and arm64 build paths. It also checks the
host release, architecture, required commands, and Clang version.
The setup script is intentionally limited to Ubuntu 26.04 amd64. Package names
and firmware paths differ on other operating systems.
## Toolchain
Lenix pins LLVM/Clang 21.1.8. The project toolchain uses the
`x86_64-unknown-mercuron` target and installs to `/opt/llvm-mercuron`:
```bash
sudo ./build-toolchain.sh
/opt/llvm-mercuron/bin/clang --version
```
The root-level script is the normal entry point. The port implementation and
version metadata live in `third-party/ports/llvm/`.
The source archive is cached under `third-party/build/distfiles/`. Build files
remain under `third-party/build/build-work/` and are not part of the source
tree.
See [docs/toolchain.md](docs/toolchain.md) and
[docs/toolchain-ports.md](docs/toolchain-ports.md) for the toolchain layout and
port details.
## Building
Use the repository scripts for a complete x86_64 build:
```bash
./rebuild.sh
```
For a debug build:
```bash
./rebuild-debug.sh
```
Both scripts use `/opt/llvm-mercuron`, rebuild the runtime and applications,
create the initrd and ext2 root filesystem, then produce UEFI and legacy boot
artifacts.
The main make targets can also be run directly:
| Target | Result |
|--------------------------|-----------------------------------------|
| `make` | x86_64 UEFI and legacy kernel artifacts |
| `make efi` | x86_64 UEFI loader |
| `make iso` | x86_64 GRUB/Multiboot2 ISO |
| `make initrd` | Initial user-mode service archive |
| `make build/rootfs.ext2` | ext2 root filesystem image |
| `make test-console` | UEFI and legacy serial input test |
| `ARCH=arm64 make` | arm64 kernel for QEMU's `virt` machine |
`ARCH` defaults to `x86_64`. Set `PACKAGE_MUSL=0` to omit musl packaging, or
`INCLUDE_MUSL_HEADERS=0` to package its loader and libraries without headers.
## Running in QEMU
Run the x86_64 UEFI path:
```bash
make run-uefi
```
Run the x86_64 legacy GRUB path:
```bash
make run-legacy
```
Run the arm64 kernel on QEMU `virt`:
```bash
ARCH=arm64 make run-arm64
```
QEMU uses the terminal for the serial console. Stop it with `Ctrl+C`.
## Testing
Run the cross-architecture smoke test and source checks from the repository
root:
```bash
./scripts/test_sanity.sh
make test-console
make lint
```
The smoke test builds and boots the supported QEMU paths, then checks for
required boot markers. `make test-console` boots both x86_64 paths and checks
that `hello`, `bench_portal_pingpong`, and a second `hello` execute in order.
Its logs are written under `build/test-logs/`. A QEMU timeout alone does not
count as a pass. Set `SANITY_TIMEOUT=<seconds>` to change the smoke test's
default timeout.
Focused test scripts and logs are under `scripts/` and `build/test-logs/`.
## Architecture
Lenix keeps mechanisms in the kernel and policy in user-mode services. The
kernel provides boot, memory management, scheduling, traps, IPC, syscall
mediation, capabilities, and the hardware access needed by services.
User-mode servers provide service discovery, VFS and filesystems, block
devices, networking, PCI, TTY, and PTY management. Applications resolve these
services through namesvc instead of using hard-coded portal handles.
The normal filesystem path is:
```text
application -> syscall -> kernel mediation -> VFS -> filesystem server
-> blockd -> block backend
```
## Repository layout
| Path | Purpose |
|----------------------|------------------------------------------|
| `kernel/` | Microkernel and architecture code |
| `servers/` | User-mode services and drivers |
| `user/runtime/` | Freestanding runtime and public headers |
| `user/apps/` | User applications and test programs |
| `user/bench/` | Microbenchmarks |
| `boot/` | x86_64 GRUB and boot assets |
| `disk/ext2root/` | Source tree for the ext2 root image |
| `scripts/` | Packaging, QEMU, lint, and test helpers |
| `third-party/ports/` | Toolchain and userland ports |
| `docs/` | Architecture and subsystem documentation |
## Documentation
- [AI_CONTEXT.md](AI_CONTEXT.md) contains the verified development,
administration, and test command matrix.
- [Architecture overview](docs/architecture/overview.md) describes the system
boundaries.
- [Boot](docs/boot.md), [IPC](docs/ipc.md), [VFS](docs/vfs.md), and
[namesvc](docs/namesvc.md) cover the main subsystems.
- [POSIX gaps](docs/posix-gap.md) records incomplete interfaces and semantics.
- [roadmap.md](roadmap.md), [TODO.md](TODO.md), and
[changelog.md](changelog.md) track planned and completed work.
## Known limitations
- x86_64 QEMU is the reference path; arm64 packaging and validation lag behind.
- SMP is disabled by default and is not considered stable.
- Boot and IPC timing can still cause intermittent hangs.
- POSIX coverage, networking, device semantics, and dynamic musl support are
incomplete.
- Distributed IPC and clustering remain planned work.
