English | 中文
This repository contains build scripts, patches, and helper tools for generating TGOS-related images. It covers:
- Platform-specific Linux, ArceOS, and StarryOS builds
- Common OS builders under
scripts/os/ - Rootfs generation under
scripts/rootfs/ - Packaging and release helpers
- Local image distribution with
http_server.py
The repository is now organized by responsibility instead of placing every script directly under scripts/.
| Path | Purpose |
|---|---|
build.sh |
Top-level entry point for OS, rootfs, and release tasks |
run.sh |
Quick QEMU boot helper for generated QEMU Linux images |
scripts/platform/ |
Platform entry scripts such as Phytium Pi, QEMU, Orange Pi, etc. |
scripts/os/ |
Common OS builders such as ArceOS, StarryOS, Zephyr, FreeRTOS, and RT-Thread |
scripts/rootfs/ |
Rootfs builders for BusyBox, Alpine, and Debian |
scripts/tools/ |
Packaging / release helpers and other utilities |
scripts/lib/ |
Shared shell helpers |
patches/ |
Patches applied to upstream projects during builds |
IMAGES/ |
Final build artifacts |
build/ |
Download caches, source trees, and temporary build output |
release/ |
Packaged archives generated by release scripts |
These scripts are the main entry points for platform-oriented builds. They usually clone upstream sources, apply patches, invoke vendor or upstream build systems, and copy results into IMAGES/.
| Script | Main responsibility |
|---|---|
scripts/platform/phytiumpi.sh |
Build Phytium Pi guest images |
scripts/platform/roc-rk3568-pc.sh |
Build ROC-RK3568-PC guest images |
scripts/platform/evm3588.sh |
Build EVM3588 guest images |
scripts/platform/tac-e400-plc.sh |
Build TAC-E400-PLC guest images |
scripts/platform/orangepi-5-plus.sh |
Build Orange Pi 5 Plus guest images |
scripts/platform/rdk-s100p.sh |
Build RDK-S100P guest images |
scripts/platform/bst-a1000.sh |
Build BST-A1000 guest images |
scripts/platform/qemu.sh |
Build QEMU guest images and invoke rootfs generation when needed |
These scripts provide reusable build flows and are called either directly or by platform scripts.
| Script | Main responsibility |
|---|---|
scripts/os/arceos.sh |
Common ArceOS builder |
scripts/os/starry.sh |
StarryOS guest-kernel builder |
scripts/os/zephyr.sh |
Common Zephyr builder |
scripts/os/freertos.sh |
Common FreeRTOS builder |
scripts/os/rtthread.sh |
Common RT-Thread builder |
These scripts generate filesystem contents or filesystem images.
| Script | Main responsibility | Typical output |
|---|---|---|
scripts/rootfs/busybox.sh |
Build a minimal BusyBox-based rootfs | initramfs-<arch>-busybox.cpio.gz, rootfs-<arch>-busybox.img |
scripts/rootfs/alpine.sh |
Download Alpine minirootfs and pack an ext4 image | rootfs-<arch>-alpine.img |
scripts/rootfs/debian.sh |
Use Docker + debootstrap to build a Debian rootfs image | rootfs-<arch>-debian.img |
build.sh os <target> supports the following platform targets:
phytiumpiroc-rk3568-pcevm3588tac-e400-plcorangepi-5-plusrdk-s100pbst-a1000qemuqemu-aarch64qemu-riscv64qemu-x86_64qemu-loongarch64
For QEMU:
qemurunsqemu-aarch64,qemu-x86_64,qemu-riscv64, andqemu-loongarch64in isolated workspaces, concurrently within the shared build budgetqemu-aarch64,qemu-riscv64,qemu-x86_64, andqemu-loongarch64are thin wrappers overscripts/platform/qemu.sh
scripts/platform/qemu.sh currently supports:
aarch64riscv64x86_64loongarch64
build.sh rootfs <target> currently supports:
busyboxalpine
scripts/rootfs/debian.sh is available directly and currently supports:
aarch64riscv64x86_64loongarch64
scripts/rootfs/alpine.sh currently supports:
aarch64loongarch64riscv64x86_64
Note:
loongarch64 is a valid Debian target in the script, but Debian trixie does not currently provide loong64 packages in the main archive. Use an appropriate suite such as sid / unstable when building that variant.
Before building, make sure the host has enough disk space, network access to the required upstream repositories or intranet SDK services, and the needed toolchains.
On Ubuntu 24.04 or a similar distribution, a practical baseline is:
sudo apt update
sudo apt install \
flex bison libelf-dev libssl-dev \
gcc-aarch64-linux-gnu g++-aarch64-linux-gnu \
gcc-riscv64-linux-gnu g++-riscv64-linux-gnu \
bc fakeroot coreutils cpio gzip rsync file \
debootstrap binfmt-support debian-archive-keyring eatmydata \
e2fsprogs util-linux fdisk docker.io \
python3 python3-venv curl git openssh-client libmpc-dev libgmp-dev \
lz4 chrpath gawk texinfo diffstat expect cmake \
clang libclang-dev libudev-devThe less obvious entries:
| Package | Required by |
|---|---|
util-linux (flock), fdisk (sfdisk) |
scripts/lib/build-lock.sh and scripts/lib/rootfs-disk.sh |
clang, libclang-dev |
bindgen, via the ax-posix-api and lwprintf-rs crates |
libudev-dev |
the libudev-sys crate, via the tgoskits xtask |
Some platform builds require:
- Access to private repositories
- Access to the intranet SDK host
10.3.10.194 - Additional vendor SDK dependencies
- Administrator privileges or passwordless sudo
build.sh is the main entry point.
./build.sh help
# Platform-oriented OS builds
./build.sh platform phytiumpi
./build.sh platform qemu all
./build.sh platform qemu-aarch64 linux
./build.sh platform qemu all --rootfs busybox,alpine,debian
# Orange Pi 5 Plus StarryOS guest kernel
./build.sh platform orangepi-5-plus starry
# Orange Pi stages and complete flashable image
./build.sh platform orangepi-5-plus linux
./build.sh platform orangepi-5-plus rootfs
./build.sh platform orangepi-5-plus all
# Rootfs builds
./build.sh rootfs busybox aarch64 --out_dir IMAGES/rootfs
./build.sh rootfs alpine riscv64 --out_dir IMAGES/rootfs/alpine-riscv64.img
# Release packaging
./build.sh release packUse platform scripts for fine-grained control:
scripts/platform/phytiumpi.sh all
scripts/platform/qemu.sh aarch64 linux
scripts/platform/qemu.sh riscv64 all
scripts/platform/evm3588.sh arceosUse rootfs scripts directly when you only need filesystem images:
scripts/rootfs/busybox.sh aarch64 --out_dir IMAGES/rootfs
scripts/rootfs/alpine.sh x86_64 --img-size 2G
scripts/rootfs/debian.sh riscv64 --debian trixie --out_dir IMAGES/rootfs
scripts/rootfs/debian.sh loongarch64 --debian unstable --out_dir IMAGES/rootfsEach ext4 builder starts from one clean base image and composes independent branches:
clean base
├── guest branch + guest test plugins -> nested rootfs
└── outer branch + outer test plugins + /guest platform payload
├── /guest/rootfs-<arch>-<type>-0.img
├── /guest/rootfs-<arch>-<type>-1.img
└── ... through -(ROOTFS_GUEST_COUNT-1).img
Guest plugins install below /guest-tests/<plugin> in the nested image. The
outer image contains platform payload below /guest and the raw nested images at
the paths above; outer-only platform files and /opt/ltp do
not leak into the nested image. There is deliberately no generated
run-all.sh: selecting tests packages their assets but does not choose a test
order or run them automatically.
For QEMU AArch64 Alpine, qemu_ivc_inject_nested_payloads() also installs the
matching /root/axvisor.ko (IVC + IVSHMEM) and /root/ivc-subscribe into every
existing nested guest image. Other guest tests and their free-space reserves are
preserved; no dedicated IVC rootfs is created, and the module is not loaded automatically.
The defaults are:
| Image scope | BusyBox | Alpine | Debian |
|---|---|---|---|
| Outer tests | none |
ltp |
none |
| Nested guest tests | cyclictest,lmbench,iozone |
cyclictest,lmbench,iozone |
cyclictest,lmbench,iozone |
ROOTFS_GUEST_COUNT defaults to 2 and accepts positive decimal integers.
All guests start with identical contents and use the same --guest-tests
selection. Tests build once; the resulting filesystem is stored as independently
writable regular files, never hardlinks. Names are always zero-based. These copies initially
share a UUID; each guest mounts its own block device.
In the platform graph, each test plugin is a leaf task. Outer/guest overlay
joins wait for their plugins, followed by rootfs and platform-image nodes. This
lets tests across architectures and platforms share the global budget, while a
plugin failure blocks only its dependent image chain.
Each guest and the outer ext4 image reserve 256 MiB free space by default;
--guest-free-size applies separately to every guest. The outer filesystem is
automatically expanded for all guest files, platform payloads, metadata, and
--outer-free-size; raw image size therefore grows approximately linearly with
ROOTFS_GUEST_COUNT. The
uncompressed nested image is embedded as a raw file, so the raw outer image can
grow substantially; release-time xz compression may still make the archive
much smaller, but no compressed-size threshold is guaranteed. BusyBox ext4
uses the same composition. Its legacy initramfs keeps existing platform
injection, but excludes guest test plugins and the nested rootfs.
Direct rootfs examples:
scripts/rootfs/busybox.sh x86_64 \
--outer-tests none --guest-tests cyclictest \
--guest-free-size 128M --outer-free-size 384M
scripts/rootfs/alpine.sh aarch64 \
--outer-tests ltp --guest-tests cyclictest,lmbench,iozone \
--guest-free-size 256M --outer-free-size 512MThe same options pass through the QEMU flow:
./build.sh platform qemu-x86_64 linux --rootfs busybox,alpine,debian \
--outer-tests none --guest-tests cyclictest \
--guest-free-size 256M --outer-free-size 512MUse none to build a scope without tests, or an explicit comma-separated list
for nondefault builds.
Executable scripts/rootfs-test-plugins/plugins/*.sh files form the extension point.
A plugin implements two commands:
describeprints exactlyname=,arches=,rootfs=, andscopes=lines.build --arch <arch> --rootfs <type> --scope <outer|guest> --output <empty-dir>writes an overlay into the supplied empty directory. Guest plugins normally useguest-tests/<name>/; outer plugins use their native outer-rootfs path.
Add a plugin by copying an existing small plugin, pinning its upstream version and SHA256, declaring only supported combinations, producing static ELF64 binaries for the selected architecture where applicable, and extending the fast plugin tests. The framework discovers plugins rather than maintaining a central list. Overlays accept directories, regular files, and symlinks only; special nodes and out-of-band metadata paths are rejected. Download caches and extracted sources are keyed by the verified checksum and record checksum provenance, while builder containers are pinned by their configured image.
Every selected plugin is rebuilt for the current invocation. Checked source downloads,
extracted source directories, and builder containers may still be reused; completed
overlay artifacts are not cached. Release compression remains xz -T0 -9e.
BusyBox is cleaned with make distclean, configured and rebuilt for every invocation.
The downloaded Git source checkout is still reused and reset to the pinned ref.
- Generates both initramfs and ext4 rootfs images
- Used by
scripts/platform/qemu.shfor QEMU Linux and ArceOS flows - Currently supports
aarch64,loongarch64,riscv64, andx86_64
- Downloads official Alpine
minirootfs - Verifies the downloaded archive with SHA256
- Produces a clean Alpine base; the default outer
ltpplugin separately builds and installs filtered LTP 20260529 content into/opt/ltp - Follows the upstream Alpine exclusions: skips the
fmtmsgdirectory and onlytimer_create01/timer_create03, while retainingtimer_create02 - Includes
/opt/ltp/Versionand executable/opt/ltp/testcases/bin/hackbench - Packages all scheduler build artifacts, but only
hackbenchis currently verified as a Starry workload - Builds LTP through the shared, checksum-verified Alpine plugin builder
- Generates an ext4 rootfs image
- Currently supports
aarch64,loongarch64,riscv64, andx86_64 scripts/tests/rootfs/alpine-ltp-content.shvalidates the LTP version, timer_create contents, runtest entries, executable bit, and ELF architecture in all four images
The Debian base filesystem is recreated with debootstrap for every invocation;
completed base ext4 images are not cached. Docker may still reuse its local builder
image, but APT packages are fetched again inside the temporary build environment.
- Uses Docker plus
debootstrap - Generates an ext4 rootfs image
- Defaults to Debian
trixie - Supports
aarch64,riscv64,x86_64, andloongarch64
Select the fast regression suites relevant to the change; running every suite is not required for each build:
scripts/tests/rootfs/rootfs-nested-content-test.sh
scripts/tests/rootfs/qemu-rootfs-test-options.sh
scripts/tests/rootfs/rootfs-builder-options.sh
scripts/tests/rootfs/rootfs-plugin-framework.sh
scripts/tests/rootfs/rootfs-compose.sh
scripts/tests/rootfs/rootfs-disk.sh
scripts/tests/platform/orangepi-rootfs-flow.sh
scripts/tests/platform/starry-release-smoke.shAfter building, validate selected image content without mounting it:
scripts/tests/rootfs/rootfs-nested-content.sh --image-dir IMAGES/rootfs \
--arch x86_64 --rootfs busybox \
--guest-tests cyclictest,lmbench,iozone \
--guest-free-size 256M --outer-free-size 256M
scripts/tests/rootfs/alpine-ltp-content.sh --image-dir IMAGES/rootfs --arch x86_64
bash scripts/tests/platform/orangepi-nested-content.sh \
--image IMAGES/rootfs/orangepi-5-plus.imgThe BusyBox end-to-end fixture build is opt-in:
scripts/tests/rootfs/rootfs-builder-options.sh --integrationOptional full QEMU validation is intentionally manual and per architecture:
./build.sh platform qemu-aarch64 all --rootfs busybox,alpine,debian
./build.sh platform qemu-riscv64 all --rootfs busybox,alpine,debian
./build.sh platform qemu-x86_64 all --rootfs busybox,alpine,debian
./build.sh platform qemu-loongarch64 all --rootfs busybox,alpineNone of these build or verification commands automatically executes a
run-all.sh; workloads must be invoked explicitly inside the guest.
Artifacts are collected under IMAGES/. Common locations include:
| Path | Contents |
|---|---|
IMAGES/qemu-<arch>/linux |
QEMU Linux kernel artifacts for the given architecture |
IMAGES/qemu-<arch>/arceos |
QEMU ArceOS binaries for the given architecture |
IMAGES/rootfs |
Standalone rootfs images generated directly by rootfs scripts |
IMAGES/<platform>/linux |
Linux artifacts for a hardware platform |
IMAGES/<platform>/arceos |
ArceOS artifacts for a hardware platform |
IMAGES/orangepi/starry/orangepi-5-plus |
StarryOS kernel for /guest/starry/orangepi-5-plus |
IMAGES/orangepi-5-plus-starry |
Standalone StarryOS release staging (image, manifest, and SHA256) |
IMAGES/rootfs/rootfs-aarch64-orangepi-jammy.img |
Orange Pi Jammy guest rootfs with the three benchmarks |
IMAGES/rootfs/orangepi-5-plus.img |
Flashable Ubuntu Jammy minimal image with a same-origin nested guest rootfs |
The Orange Pi commands have separate outputs. Build only the kernel and DTB with:
./build.sh platform orangepi-5-plus linuxBuild only the Jammy guest rootfs containing the three benchmarks with:
./build.sh platform orangepi-5-plus rootfsBuild every Orange Pi payload and the final flashable image with:
./build.sh platform orangepi-5-plus allall builds Linux, U-Boot, ArceOS, StarryOS, Zephyr, FreeRTOS, the AXIVC payloads,
and the benchmark guest rootfs before publishing IMAGES/rootfs/orangepi-5-plus.img.
Individual build commands do not publish that image. The final Ubuntu Jammy minimal
root filesystem contains all platform payloads under /guest and the nested rootfs:
/guest/rootfs-aarch64-orangepi-jammy-0.img
/guest/rootfs-aarch64-orangepi-jammy-1.img
└── /guest-tests/
├── cyclictest/
├── lmbench/
└── iozone/
The guest ext4 is built from the pinned Orange Pi Jammy rootfs archive and receives
the three statically linked AArch64 workloads before final image composition. The
nested and outer filesystems reserve 256 MiB each by default. The build requires
lz4, mke2fs, sfdisk, python3, debugfs, dumpe2fs, e2fsck, and
resize2fs, but does not require loop mounts for image composition. It packages the
workloads without running them. Validate a completed image with:
bash scripts/tests/platform/orangepi-nested-content.sh \
--image IMAGES/rootfs/orangepi-5-plus.imgUse the unified platform entry point:
./build.sh platform orangepi-5-plus starryThe builder uses os/StarryOS/configs/board/orangepi-5-plus.toml from the
tgoskits dev branch by default and applies a small local configuration patch
that enables the upstream ax-driver/virtio-blk feature. The driver itself is
provided by tgoskits; no driver implementation is maintained here.
The generated manifest.toml records the base commit used. Override it
explicitly for revision-specific builds:
./build.sh platform orangepi-5-plus starry --ref <tgoskits-commit>The guest kernel is written to IMAGES/orangepi/starry/orangepi-5-plus and the
standalone release staging directory is IMAGES/orangepi-5-plus-starry/.
./build.sh release pack creates release/orangepi-5-plus-starry.tar.xz.
Clean both outputs with:
./build.sh platform orangepi-5-plus starry cleanRun the deterministic packaging and registry smoke test with:
scripts/tests/platform/starry-release-smoke.shTypical QEMU Linux files:
Imageforaarch64/riscv64bzImageforx86_64vmlinuz.efiandvmlinux.elfforloongarch64linux-qemuas the generic QEMU Linux entry name; forloongarch64, this is the ELF image copied fromvmlinux.elf- BusyBox rootfs artifacts such as
initramfs-<arch>-busybox.cpio.gzandrootfs-<arch>-busybox.img
Use run.sh for quick local QEMU validation:
./run.sh aarch64 ramfs
./run.sh riscv64 rootfs
./run.sh x86_64 rootfsQEMU platform build outputs now live under IMAGES/qemu-<arch>/.
For LoongArch64, the platform archive qemu-loongarch64.tar.xz contains both
linux/vmlinuz.efi and linux/vmlinux.elf; linux/linux-qemu is the generic
entry name used by the QEMU platform flow and points at vmlinux.elf. Rootfs
images are published separately, including
initramfs-loongarch64-busybox.cpio.gz.tar.xz,
rootfs-loongarch64-busybox.img.tar.xz, and
rootfs-loongarch64-alpine.img.tar.xz by default.
./build.sh release pack
# Or call the script directly
scripts/tools/pack.sh --in_dir IMAGES --out_dir release--pack IMAGES,release means packaging artifacts from IMAGES/ first, then publishing the files generated under release/.
./build.sh release github \
--pack IMAGES,release \
--token <GITHUB_TOKEN> \
--repo rcore-os/tgosimages \
--tag v0.0.10
# Or call the script directly
scripts/tools/github.sh \
--pack IMAGES,release \
--token <GITHUB_TOKEN> \
--repo rcore-os/tgosimages \
--tag v0.0.10http_server.py serves files from IMAGES/ using Python's standard library.
python3 http_server.py start
python3 http_server.py status
python3 http_server.py restart -p 9000 -b 127.0.0.1
python3 http_server.py stopWhen exposing the server on a shared network, restrict access with firewalls or a reverse proxy.
Contributions are welcome for:
- New platform scripts
- Improvements to build flows
- Rootfs generation updates
- Documentation fixes
Before sending a pull request, please keep script style consistent and document how to reproduce your result.
This project is licensed under the MIT License. See LICENSE for details.
./build.sh platform ... and direct scripts/platform/*.sh invocations share this layout:
logs/platform/<platform>-<action>-<timestamp>-<unique-id>/
├── build.log # Serial stages, child output, and parallel scheduling
├── summary.log # Invocation start, final result, and exit status
└── steps/ # Each parallel group's summary.log and per-step logs
Detailed parallel compiler output stays in steps/; serial preparation and image postprocessing output stays in build.log. Use the top-level summary.log for the overall result: completion of a parallel group does not imply successful postprocessing. QEMU directory names include the architecture and action. Help commands do not create default logs.
Set LOG_DIR=/path/to/logs to change the log root. An explicit LOG_FILE preserves caller-managed logging; LOG_CREATE_DEFAULT_FILE=0 disables automatic invocation logs (parallel step logs are still created). Existing logs are neither moved nor removed.
platform all and platform qemu all share the same batch progress display: START, STARTED, RUNNING (every 60 seconds by default), DONE / FAILED, and COMPLETE. Board targets remain sequential; the QEMU phase runs architectures concurrently and aggregates failures after collecting all results. Failed tasks print the last 20 log lines. Batch directories contain summary.log, <target>.log, and steps/; verbose compiler output goes to target logs. Set PARALLEL_HEARTBEAT_INTERVAL to adjust the progress interval in seconds.
Console messages use cyan for progress, green for success, yellow for warnings,
and red for failures, without per-node or per-architecture identity colors.
LOG_COLOR=auto (default) colors terminals only and honors NO_COLOR.
Use LOG_COLOR=always to force colors or LOG_COLOR=never to disable them.
Framework log files remain plain text.
Host build entry points (platform, os, rootfs, apps, release) and helper scripts share scripts/lib/log.sh. Messages use [YYYY-MM-DD HH:MM:SS] [INFO|SUCCESS|WARN|ERROR|DEBUG] message; VERBOSE=1 enables DEBUG. Single tasks announce automatically created log files. Platform, OS, and rootfs batches share progress formatting and failure excerpts (last 20 lines), preserving sequential/parallel scheduling and rootfs architecture progress reporting. Raw tool output and machine-readable output retain their original form.
Common build adapters manage compiler budgets, caches and timing. Explicit input declarations enable patch-aware source preparation and whole-task caching. See the build framework guide for target integration, configuration and invalidation rules.
./build.sh platform qemu allBy default, the total compiler budget is five eighths of the logical CPUs
available to the process. The graph starts with approximately the square root
of that budget in concurrent slots; with cgroup metrics, it adjusts admission
for new nodes according to CPU use and CPU, I/O, and memory pressure from the
same build cgroup. Running tools keep their original -j, while the scheduler
can reclaim their reservations to start new nodes. Without metrics the
conservative starting cap remains fixed.
Set BUILD_PARALLEL_TASKS to override the cap and disable automatic adjustment.
Architecture workspaces live under build/workspaces/qemu-<arch>/. Direct
single-architecture commands use the same workspace and lock as batch builds.
Git downloads are shared under build/.cache/git/; checkouts and patch states
are independent. Existing build directories are preserved, so the first run in
the new workspace performs a fresh preparation.