One deterministic build chain.

GN/Ninja compiles boot, hypervisor, kernel and userspace components; scripts assemble the images and start the target platform.

Set up the toolchain.

TOOLCHAIN

Cross compiler

TranquilOS produces freestanding AArch64 binaries, so the host's default compiler won't do. Download a toolchain from newos.org/toolchains and extract it into the repository's toolchains/ directory. The default is aarch64-elf (GCC 12.2.0 for bare-metal targets).

MACOS ONLY

e2fsprogs

system.img is an ext2 filesystem image. Assembling it on macOS requires Homebrew's e2fsprogs. Without it, compilation can succeed while image assembly fails.

brew install e2fsprogs

Note: env_setup.sh must be sourced in every new shell — it exports OS_BASE_DIR=~/kernel and puts gn and the compilers on PATH. OS_BASE_DIR is hardcoded to ~/kernel; if you checked the repo out elsewhere, edit it first.

One command to build and boot.

QemuVirt is the primary development platform. The script builds, assembles the images and starts a 4-core VM with ramfb and VirtIO.

Skip the build? Get prebuilt images →

quick start — qemu virt

$ git clone https://github.com/nerossoft/TranquilOS kernel $ cd kernel # after extracting the toolchain into toolchains/: $ source env_setup.sh && ./run_qemu_virt.sh ✓ gn gen out --args='platform="QemuVirt"' ✓ ninja: boot · hypervisor · kernel · systemd · apps ✓ boot.img (64M) · system.img (128M, ext2) ✓ qemu virt: 4 cores · 2G · HVF · ramfb 800×480

Four boot targets.

Platform	Script	Display	Notes
QemuVirt	`./run_qemu_virt.sh`	ramfb graphics	Primary dev platform. VirtIO console/block/net/input/sound — the most complete device set.
Pi3B (QEMU)	`./run_qemu_pi3b.sh`	`-nographic` serial	Raspberry Pi 3B emulation, headless — good for serial-path validation.
Pi4B (QEMU)	`./run_qemu_pi4b.sh`	SD card image	Boots from an MBR-partitioned SD image built by `mkpiimg.sh`.
CM4 (hardware)	`./run_board_cm4.sh`	HDMI	Real hardware. Flashes a Compute Module 4 over USB via `rpiboot`; requires a carrier board.

Manual and single-target builds.

source env_setup.sh

# configure (platform defaults to QemuVirt, can be omitted)
gn gen out --args='platform="QemuVirt"'

# full build
ninja -C out

# build a single service / app
ninja -C out Windowmgr

Toolchain	Use
`aarch64-elf`	Default; macOS cross-compile (GCC 12.2.0)
`aarch64-linux-gnu`	Linux cross-compile; install separately
`clang`	Clang build; install separately
`hostgcc`	Host GCC, for tooling targets

Switch toolchains with gn gen out --args='toolchain="clang"'. GN targets come in only four kinds: executable / source_set / group / config. Every userspace executable provides _start via libcrt/start.S and links a platform-specific linker script.

The four stages behind every run script.

01build.sh

gn gen + ninja: compile all ELFs — bootloader, hypervisor, kernel, SystemDaemon, services and apps.

02make_boot_img.sh

objcopy ELFs to raw binaries, then dd them into the 64 MB boot.img at fixed offsets.

03make_system_img.sh

Strip ELFs, then build the 128 MB ext2 system.img via mke2fs + debugfs with services, apps, fonts and configs.

04run.sh

Launch QEMU: 4-core SMP, 2 GB RAM, HVF on macOS, VirtIO devices and a ramfb display.

boot.img (64MB)
  offset 0      Bootloader    8MB
  offset 2048   DTB           8MB
  offset 4096   Hypervisor   16MB
  offset 8192   Kernel       16MB
  offset 12288  SystemDaemon  8MB
  offset 14336  Ramdisk cpio  8MB

system.img (128MB, ext2)
  bin/   framework services
  apps/  user applications
  etc/   fonts · icons · init config

# QEMU backends can be overridden via env:
QEMU_DISPLAY_BACKEND="cocoa,zoom-interpolation=on,..."
QEMU_SERIAL_BACKEND="mon:stdio"
QEMU_MONITOR_BACKEND="none"

A tour of the source tree.

sys/

System foundation (TCB): kernel/ microkernel, virt/ hypervisor, boot/ bootloader, uapps/ init & core services, ulibs/ libc, syscall and other low-level libraries.

os/

OS userspace: base/ zygote & netmgr, framework/ window/app/font/audio services, apps/ user applications, libs/ shared libraries, thrid_party/ third-party sources.

platform/

Per-platform configs: DTBs, linker scripts, firmware and build/run scripts for QemuVirt, Pi3b, Pi4b and CM4.

build/

The GN build system and toolchain definitions.

images/

Ramdisk (cpio) and system image templates.

docs/

Design documents: basic_theory, microkernel_design, idl, async_ipc_design.