Skip to content

About

tgosimages

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

TGOS Images Repository

English | 中文

Introduction

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/.

Repository Layout

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

Script Map

Platform 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

Common OS Builders

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

Rootfs Builders

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

Supported Targets

Platform OS Targets

build.sh os <target> supports the following platform targets:

  • phytiumpi
  • roc-rk3568-pc
  • evm3588
  • tac-e400-plc
  • orangepi-5-plus
  • rdk-s100p
  • bst-a1000
  • qemu
  • qemu-aarch64
  • qemu-riscv64
  • qemu-x86_64
  • qemu-loongarch64

For QEMU:

  • qemu runs qemu-aarch64, qemu-x86_64, qemu-riscv64, and qemu-loongarch64 in isolated workspaces, concurrently within the shared build budget
  • qemu-aarch64, qemu-riscv64, qemu-x86_64, and qemu-loongarch64 are thin wrappers over scripts/platform/qemu.sh

scripts/platform/qemu.sh currently supports:

  • aarch64
  • riscv64
  • x86_64
  • loongarch64

Rootfs Targets

build.sh rootfs <target> currently supports:

  • busybox
  • alpine

scripts/rootfs/debian.sh is available directly and currently supports:

  • aarch64
  • riscv64
  • x86_64
  • loongarch64

scripts/rootfs/alpine.sh currently supports:

  • aarch64
  • loongarch64
  • riscv64
  • x86_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.

Build Prerequisites

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-dev

The 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

Quick Start

Unified Entry Point

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 pack

Direct Script Usage

Use 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 arceos

Use 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/rootfs

Rootfs Notes

Outer and nested images

Each 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 512M

The 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 512M

Use none to build a scope without tests, or an explicit comma-separated list for nondefault builds.

Rootfs test plugins

Executable scripts/rootfs-test-plugins/plugins/*.sh files form the extension point. A plugin implements two commands:

  • describe prints exactly name=, arches=, rootfs=, and scopes= lines.
  • build --arch <arch> --rootfs <type> --scope <outer|guest> --output <empty-dir> writes an overlay into the supplied empty directory. Guest plugins normally use guest-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

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.sh for QEMU Linux and ArceOS flows
  • Currently supports aarch64, loongarch64, riscv64, and x86_64

Alpine

  • Downloads official Alpine minirootfs
  • Verifies the downloaded archive with SHA256
  • Produces a clean Alpine base; the default outer ltp plugin separately builds and installs filtered LTP 20260529 content into /opt/ltp
  • Follows the upstream Alpine exclusions: skips the fmtmsg directory and only timer_create01/timer_create03, while retaining timer_create02
  • Includes /opt/ltp/Version and executable /opt/ltp/testcases/bin/hackbench
  • Packages all scheduler build artifacts, but only hackbench is 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, and x86_64
  • scripts/tests/rootfs/alpine-ltp-content.sh validates the LTP version, timer_create contents, runtest entries, executable bit, and ELF architecture in all four images

Debian

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, and loongarch64

Rootfs validation

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.sh

After 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.img

The BusyBox end-to-end fixture build is opt-in:

scripts/tests/rootfs/rootfs-builder-options.sh --integration

Optional 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,alpine

None of these build or verification commands automatically executes a run-all.sh; workloads must be invoked explicitly inside the guest.

Output Layout

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

Orange Pi 5 Plus Linux image

The Orange Pi commands have separate outputs. Build only the kernel and DTB with:

./build.sh platform orangepi-5-plus linux

Build only the Jammy guest rootfs containing the three benchmarks with:

./build.sh platform orangepi-5-plus rootfs

Build every Orange Pi payload and the final flashable image with:

./build.sh platform orangepi-5-plus all

all 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.img

Orange Pi 5 Plus StarryOS

Use the unified platform entry point:

./build.sh platform orangepi-5-plus starry

The 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 clean

Run the deterministic packaging and registry smoke test with:

scripts/tests/platform/starry-release-smoke.sh

Typical QEMU Linux files:

  • Image for aarch64 / riscv64
  • bzImage for x86_64
  • vmlinuz.efi and vmlinux.elf for loongarch64
  • linux-qemu as the generic QEMU Linux entry name; for loongarch64, this is the ELF image copied from vmlinux.elf
  • BusyBox rootfs artifacts such as initramfs-<arch>-busybox.cpio.gz and rootfs-<arch>-busybox.img

QEMU Validation

Use run.sh for quick local QEMU validation:

./run.sh aarch64 ramfs
./run.sh riscv64 rootfs
./run.sh x86_64 rootfs

QEMU 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.

Packaging and Release

Package Artifacts

./build.sh release pack

# Or call the script directly
scripts/tools/pack.sh --in_dir IMAGES --out_dir release

Publish to GitHub 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.10

Local Distribution

http_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 stop

When exposing the server on a shared network, restrict access with firewalls or a reverse proxy.

Contributing

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.

License

This project is licensed under the MIT License. See LICENSE for details.

Platform build logs

./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.

Shared log display

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.

Shared build acceleration

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 all

By 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.

About

tgosimages

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages