构建 — TranquilOS

准备工具链。

TOOLCHAIN

交叉编译器

TranquilOS 产出 freestanding AArch64 二进制，不能用宿主机默认编译器。从 newos.org/toolchains 下载工具链并解压到仓库 toolchains/ 目录。默认使用 aarch64-elf（面向 bare-metal 的 GCC 12.2.0）。

MACOS ONLY

e2fsprogs

system.img 是 ext2 文件系统镜像。macOS 上组装镜像依赖 Homebrew 的 e2fsprogs。缺少它时编译可以成功，但镜像组装会失败。

brew install e2fsprogs

注意：env_setup.sh 必须在每个新 shell 中 source，它导出 OS_BASE_DIR=~/kernel 并把 gn 与编译器加入 PATH。OS_BASE_DIR 硬编码为 ~/kernel——仓库检出到其他路径时先修改它。

一条命令，构建并启动。

QemuVirt 是主要开发平台。脚本完成构建、镜像组装并启动带 ramfb 与 VirtIO 的 4 核虚拟机。

不想编译？下载预构建镜像 →

quick start — qemu virt

$ git clone https://github.com/nerossoft/TranquilOS kernel $ cd kernel # 解压工具链到 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

四个启动目标。

平台	脚本	显示	说明
QemuVirt	`./run_qemu_virt.sh`	ramfb 图形	主要开发平台。VirtIO console/block/net/input/sound，设备组合最完整。
Pi3B (QEMU)	`./run_qemu_pi3b.sh`	`-nographic` 串口	树莓派 3B 模拟，headless，适合串口路径验证。
Pi4B (QEMU)	`./run_qemu_pi4b.sh`	SD 卡镜像	经 `mkpiimg.sh` 生成 MBR 分区 SD 镜像启动。
CM4（真机）	`./run_board_cm4.sh`	HDMI	真实硬件。经 USB 以 `rpiboot` 刷写 Compute Module 4，需要实体底板。

手动构建与单目标编译。

source env_setup.sh

# 配置（platform 默认 QemuVirt，可省略）
gn gen out --args='platform="QemuVirt"'

# 全量构建
ninja -C out

# 只构建某个服务 / 应用
ninja -C out Windowmgr

工具链	用途
`aarch64-elf`	默认，macOS 交叉编译（GCC 12.2.0）
`aarch64-linux-gnu`	Linux 交叉编译，需自行安装
`clang`	Clang 构建，需自行安装
`hostgcc`	宿主 GCC，用于工具类目标

切换工具链：gn gen out --args='toolchain="clang"'。GN 目标只有四种：executable / source_set / group / config；每个用户态可执行文件以 libcrt/start.S 提供 _start，并链接平台专用链接脚本。

run 脚本背后的四步流水线。

01build.sh

gn gen + ninja：编译全部 ELF——bootloader、hypervisor、kernel、SystemDaemon、服务与应用。

02make_boot_img.sh

objcopy 转 raw binary，按固定偏移 dd 进 64MB boot.img。

03make_system_img.sh

strip ELF，经 mke2fs + debugfs 生成 128MB ext2 system.img，写入服务、应用、字体与配置。

04run.sh

启动 QEMU：4 核 SMP、2G 内存、macOS HVF 加速、VirtIO 设备与 ramfb 显示。

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 后端可用环境变量覆盖：
QEMU_DISPLAY_BACKEND="cocoa,zoom-interpolation=on,..."
QEMU_SERIAL_BACKEND="mon:stdio"
QEMU_MONITOR_BACKEND="none"

源码树导览。

sys/

系统基础（TCB）：kernel/ 微内核、virt/ hypervisor、boot/ 引导、uapps/ init 与核心服务、ulibs/ libc 与 syscall 等底层库。

os/

OS 用户态：base/ zygote 与 netmgr、framework/ 窗口/应用/字体/音频等服务、apps/ 用户应用、libs/ 共享库、thrid_party/ 三方源码。

platform/

平台配置：QemuVirt、Pi3b、Pi4b、CM4 各自的 DTB、链接脚本、固件与构建/运行脚本。

build/

GN 构建系统与工具链定义。

images/

ramdisk（cpio）与 system 镜像模板。

docs/

设计文档：basic_theory、microkernel_design、idl、async_ipc_design。

一条确定的构建链。