Quickstart

Build x86_64 on a Linux host, then boot and self-test with QEMU.

On this page

Build environment

This first-run path assumes an x86_64 Linux host and Debian/Ubuntu apt package names. It boots a QEMU guest without writing the host boot disk. Linux 6.6.0-rt15 and BusyBox 1.37.0 sources are vendored. Networking is needed to install dependencies and obtain the repository, not to download these sources during the build. README gives a baseline budget of about 10 GB free disk; multiple architectures or clean build directories need additional space.

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 supply the native C toolchain and static-link development files. flex, bison, bc, Perl, and OpenSSL/ELF development packages support kernel building; cpio/gzip pack initramfs; kmod supplies depmod; binutils supplies readelf; coreutils/findutils/grep/sed support scripts.

Install libncurses-dev additionally for manual menuconfig.

Build and QEMU run as a normal user; only apt installation needs sudo.

Host preflight: in particular, confirm GNU cpio supports --reproducible.

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

Get source

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

Pinning the commit keeps these commands aligned with the documented sources; it does not require long-term work on detached HEAD. Create a branch from this baseline for development. prepare_linux.sh should report bundled_release=6.6.0-rt15 and xtos_integration=present; verify_source_tree.sh should report source_tree=pass. These check source prerequisites, not successful boot.

Build x86_64

bash

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

The script builds the kernel and modules, then static BusyBox, copies SDKs/tools/examples into .build/userspace-source for compilation, installs the rootfs and module dependency indexes, and packs initramfs. build_system.sh defaults JOBS to 2. nproc explicitly selects the visible CPU count, not a guarantee of sufficient memory. If compiler processes are killed by memory limits, lower JOBS to 2 or less and rebuild.

Host artifact	Purpose
.build/images/xtos-bzImage	x86_64 kernel image loaded by QEMU -kernel.
.build/images/xtos-rootfs.cpio.gz	Initramfs containing static userland, modules, SDKs, and tests.
.build/images/kernel.config	Snapshot of the final kernel configuration for this build.
.build/rootfs/	Unpacked root filesystem for inspecting installed content.

A successful build ends with system_build=pass.

To use a custom directory, export an absolute path such as BUILD_ROOT="$PWD/.build-demo" and keep that value for every subsequent build, verify, and run call; otherwise verification returns to the default .build.

Do not treat generated files under .build as editable source.

Run self-test

bash

QEMU_TIMEOUT=180 ./scripts/verify_system.sh

This command boots a pc virtual machine with 512 MiB memory, 2 vCPUs, and a ttyS0 serial console, passing xtos.selftest=1 to /init.

The guest checks /sys/kernel/realtime=1, configuration, and modules; runs test_rt, test_spsc, test_signal, the CSV pipeline, and a 20-iteration signal benchmark; then powers off.

Host output is saved to .build/system-qemu.log.

Markers to inspect on success; not a complete transcript of a particular run.

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

Success requires verify_system.sh to exit 0, QEMU to exit normally, an exact XTOS_SYSTEM_TEST=PASS line in the log, and no XTOS_SYSTEM_TEST=FAIL or Kernel panic. system_build=pass, a Linux boot banner, or realtime=1 alone does not replace these conditions.

The default timeout is 120 seconds; this page explicitly uses 180.

A timeout calls for log inspection, not a pass declaration.

Interactive checks

Run on the host; this starts x86_64 QEMU, not a hardware installation.

./scripts/run_system.sh

Without the self-test parameter, /init displays the local development console and enters a BusyBox shell. After the # prompt appears, execute the following commands in the guest. Do not run these guest paths in the host shell or mistake the post-self-test shutdown state for an interactive terminal.

Execute inside the x86_64 guest 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 should report 6.6.0-rt15, realtime should be 1, and the CSV pipeline should return status="ok". Timings vary with the host and QEMU environment; they need not match website examples. Use poweroff -f in the guest to shut down, or QEMU Ctrl+a followed by x to exit. /run outputs are in memory and are not automatically persisted on shutdown.

Cross architectures

After x86_64, cross-build the same public sources. Install the additional packages below and build and verify each architecture sequentially. Install libc6-dev-riscv64-cross explicitly: GCC commonly lists it only as Recommends, so disabling recommended packages can omit static libc and development headers and break BusyBox or static test links. libc6-dev-arm64-cross is also listed explicitly for ARM64.

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

The Debian/Ubuntu RISC-V QEMU installation entry is generally qemu-system-misc, not an apt package named qemu-system-riscv64; newer Debian pulls in qemu-system-riscv as a dependency. Scripts require /usr/share/qemu/opensbi-riscv64-generic-fw_dynamic.bin to exist. Cross-architecture guest checks require realtime=1, xtos_modules=pass, guest_test_rt/test_spsc/test_signal=pass, guest_userspace=pass, and XTOS_GUEST_CHECK=DONE. See Build and Run for details.

Limits and source

Command references at commit 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, and architecture-specific build_system/verify_system/verify_guest scripts. Dependencies cover the tools those scripts call; RISC-V static libc comes from libc6-dev-riscv64-cross.