lenix.git

A 64-bit POSIX-compliant microkernel and Unix-like operating system

Visibility: public

Anonymous clone: ssh://anonymous@code.cgx.li/lenix.git

Browse commits and files on code.cgx.li

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

Ubuntu 26.04 LTS on amd64 is the supported build and QEMU test host. From the repository root:

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:

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:

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 and docs/toolchain-ports.md for the toolchain layout and port details.

Building

Use the repository scripts for a complete x86_64 build:

./rebuild.sh

For a debug build:

./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:

make run-uefi

Run the x86_64 legacy GRUB path:

make run-legacy

Run the arm64 kernel on QEMU virt:

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:

./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:

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

Known limitations