快速开始

在 Linux 主机构建 x86_64 系统，并用 QEMU 启动和自检。

本页目录

构建环境

这条首次体验路径以 x86_64 Linux 主机和 Debian/Ubuntu 的 apt 包名为准，在 QEMU 中启动客体，不写入宿主引导盘。仓库已包含 Linux 6.6.0-rt15 与 BusyBox 1.37.0 源码；联网用于安装依赖和获取仓库，构建本身不下载这两套源码。README 给出约 10 GB 可用磁盘的基础预算；多架构和多个干净构建目录需要额外空间。

bash

sudo apt-get update
sudo apt-get install -y \
  bash git build-essential libc6-dev flex bison bc libssl-dev libelf-dev \
  cpio gzip rsync python3 kmod binutils file patch perl pkg-config \
  coreutils findutils grep sed diffutils qemu-system-x86

build-essential/libc6-dev 提供本机 C 工具链和静态链接开发文件；flex、bison、bc、Perl、OpenSSL/ELF 开发包用于内核；cpio/gzip 打包 initramfs；kmod 提供 depmod；binutils 提供 readelf；coreutils/findutils/grep/sed 支撑脚本。

若要手动运行 menuconfig，再安装 libncurses-dev。

构建和 QEMU 使用普通用户运行，仅 apt 安装需要 sudo。

主机预检：尤其确认 GNU cpio 支持 --reproducible。

command -v gcc make cpio gzip depmod python3 readelf qemu-system-x86_64
cpio --help | grep -- --reproducible
df -h .

获取源码

bash

git clone https://github.com/Aitaide/OpenXTOS.git
cd OpenXTOS
git checkout --detach dd313955ad57542bcd2af8827157d1bbd0cf5e83
git rev-parse HEAD
git status --short
./scripts/prepare_linux.sh
./scripts/verify_source_tree.sh

固定提交是为了让本页命令与源码对应，不是要求长期停留在 detached HEAD。开发时可从该基线另建分支。prepare_linux.sh 的检查应报告 bundled_release=6.6.0-rt15 和 xtos_integration=present；verify_source_tree.sh 应报告 source_tree=pass。这些是源码前提检查，不是启动通过结果。

构建 x86_64

bash

JOBS=$(nproc) ./scripts/build_system.sh

脚本先构建内核和模块，再构建静态 BusyBox，复制 SDK/工具/示例到 .build/userspace-source 编译，安装 rootfs 和模块依赖索引，最后生成 initramfs。build_system.sh 的 JOBS 默认是 2；nproc 表示主动选择主机可见 CPU 数，不保证内存足够。若编译进程被内存限制终止，应改用 JOBS=2 或更低并重新构建。

主机产物	作用
.build/images/xtos-bzImage	可由 QEMU -kernel 加载的 x86_64 内核镜像。
.build/images/xtos-rootfs.cpio.gz	静态用户态、模块、SDK 与测试的 initramfs。
.build/images/kernel.config	本次构建的最终内核配置快照。
.build/rootfs/	打包前的根文件系统目录，可用于定位安装内容。

成功构建最后打印 system_build=pass。

若指定自定义目录，用绝对路径 export BUILD_ROOT="$PWD/.build-demo"，并在所有后续 build、verify 和 run 调用中保留相同值；否则验证会回到默认 .build 寻找镜像。

不要把 .build 中的可生成文件作为源码修改。

运行自检

bash

QEMU_TIMEOUT=180 ./scripts/verify_system.sh

该命令启动 pc 虚拟机，使用 512 MiB 内存、2 个 vCPU 和 ttyS0 串口，将 xtos.selftest=1 传入 /init。

客体确认 /sys/kernel/realtime=1、内核配置和模块，执行 test_rt、test_spsc、test_signal、CSV 管线及 20 次迭代的信号基准，然后关机。

主机输出保存在 .build/system-qemu.log。

通过时需要检查的标记；不是每次运行的完整输出。

system_qemu=pass
realtime=1
xtos_modules=pass
guest_userspace=pass
XTOS_SYSTEM_TEST=PASS

通过条件是 verify_system.sh 退出 0，QEMU 正常退出，日志包含完整行 XTOS_SYSTEM_TEST=PASS，且没有 XTOS_SYSTEM_TEST=FAIL 或 Kernel panic。

system_build=pass、看到 Linux 启动横幅或单独出现 realtime=1 都不足以替代完整条件。

超时默认 120 秒，本页显式给出 180 秒；超时应读日志定位，而不是当作测试通过。

交互检查

在主机执行；它启动 x86_64 QEMU，不是把系统安装到硬件。

./scripts/run_system.sh

不带自检参数的 /init 显示本地开发控制台并进入 BusyBox shell。看到 # 提示符后，在客体执行下面命令。不要在主机 shell 执行这些客体路径；也不要把自检关机后的状态当成交互终端。

在 x86_64 客体 shell 中执行。

uname -r
cat /sys/kernel/realtime
zcat /proc/config.gz | grep '^CONFIG_PREEMPT_RT='
modprobe xtos_bci_core
modprobe xtos_bci_buffer
modprobe openbci_cyton
cat /proc/modules
/usr/libexec/xtos/test_rt
/usr/libexec/xtos/test_spsc
/usr/libexec/xtos/test_signal
xtos-eeg-pipeline --input /usr/share/xtos/fixtures/valid.csv
xtos-signal-benchmark --iterations 20 --output /run/signal-benchmark.json
cat /run/signal-benchmark.json

uname 应显示 6.6.0-rt15，realtime 应是 1，CSV 管线应返回 status="ok"。具体耗时随主机与 QEMU 环境变化，不需要匹配网站示例数值。客体可用 poweroff -f 关机；QEMU 的 Ctrl+a 再按 x 也可退出。/run 中输出位于内存，关闭后不会自动持久化。

跨架构

完成 x86_64 后，可使用相同公开源码交叉构建。安装下面附加依赖，再按架构顺序串行构建与验证。libc6-dev-riscv64-cross 必须明确安装：GCC 包通常只把它列为 Recommends，禁用推荐包时会缺少静态 libc 与开发头，导致 BusyBox 或静态测试链接失败。ARM64 同理显式列出 libc6-dev-arm64-cross。

bash

sudo apt-get install -y \
  crossbuild-essential-arm64 libc6-dev-arm64-cross qemu-system-arm \
  gcc-riscv64-linux-gnu binutils-riscv64-linux-gnu \
  libc6-dev-riscv64-cross qemu-system-misc opensbi

bash

JOBS=$(nproc) ./scripts/build_system_arm64.sh
QEMU_TIMEOUT=180 ./scripts/verify_system_arm64.sh
QEMU_TIMEOUT=300 ./scripts/verify_guest_arm64.sh

JOBS=$(nproc) ./scripts/build_system_riscv64.sh
QEMU_TIMEOUT=300 ./scripts/verify_system_riscv64.sh
QEMU_TIMEOUT=360 ./scripts/verify_guest_riscv64.sh

Debian/Ubuntu 的 RISC-V QEMU 安装入口通常是 qemu-system-misc，不是一个叫 qemu-system-riscv64 的 apt 包；较新 Debian 会通过依赖拉入 qemu-system-riscv。脚本要求 /usr/share/qemu/opensbi-riscv64-generic-fw_dynamic.bin 确实存在。跨架构客体检查需要 realtime=1、xtos_modules=pass、guest_test_rt/test_spsc/test_signal=pass、guest_userspace=pass 和 XTOS_GUEST_CHECK=DONE；详见“构建系统”和“运行与验证”。

限制与源码

命令依据：提交 dd313955ad57542bcd2af8827157d1bbd0cf5e83 的 scripts/prepare_linux.sh、scripts/verify_source_tree.sh、scripts/build_system.sh、scripts/run_system.sh、scripts/verify_system.sh、system/rootfs/init、system/rootfs/usr/bin/xtos-selftest 及各架构 build_system/verify_system/verify_guest 脚本。依赖按这些脚本实际调用的工具列出；RISC-V 静态 libc 来自 libc6-dev-riscv64-cross。