class

Bootstrap::SysrootBuilder

Inherits Bootstrap::CLI < Reference < Object

SysrootBuilder prepares a chroot-able environment that can rebuild a complete sysroot using source tarballs cached on the host. The default seed uses Alpine’s minirootfs, but the seed rootfs, architecture, and package set are intended to be swappable once self-hosted variants exist.

Key expectations:

  • No shell-based downloads: HTTP/Digest from Crystal stdlib only.
  • Deterministic source handling: every tarball is cached locally with CRC32 + SHA256 bookkeeping for reuse and verification.
  • bootstrap-qcow2 source is fetched as a tarball and staged into the inner rootfs workspace (/workspace inside the inner rootfs).

Usage references:

  • CLI entrypoints: bq2 sysroot-builder and bq2 sysroot-plan-write, (see self.run, help_entries, and README).
  • Workspace layout: host workspace is data/sysroot. The inner workspace is /workspace inside the inner rootfs and /workspace/rootfs/workspace from the outer rootfs.
  • Build plan contract: write_plan persists the plan consumed by SysrootRunner under the inner rootfs var/lib directory.

Constants

BQ2_SEED_NAME = "bq2-rootfs-0.3.3"
CA_BUNDLE_PEM = {{ read_file("/tmp/tmp.OhikoG/src/src/../data/ca-bundle/ca-certificates.crt") }}

Source: https://curl.se/ca/cacert.pem (Mozilla CA certificate bundle).

DEFAULT_ARCH = "x86_64"
DEFAULT_BDWGC = "8.2.6"
DEFAULT_BQ2_SEED_URL = "https://dl.beagle.cc/images/bq2-rootfs-0.3.3.tar.gz"

Source: https://dl.beagle.cc/images/bq2-rootfs-0.3.3.tar.gz

DEFAULT_BUSYBOX = "1.36.1"
DEFAULT_CMAKE = "3.29.6"
DEFAULT_CRYSTAL = "1.19.1"
DEFAULT_FOSSIL = "2.25"
DEFAULT_GIT = "2.45.2"
DEFAULT_GMP = "6.3.0"
DEFAULT_GNU_MAKE = "4.4.1"
DEFAULT_LIBATOMIC_OPS = "7.8.2"
DEFAULT_LIBFFI = "3.4.6"
DEFAULT_LIBICONV = "1.17"
DEFAULT_LIBRESSL = "3.8.2"
DEFAULT_LIBXML2 = "2.12.7"
DEFAULT_LIBYAML = "0.2.5"
DEFAULT_LINUX = "6.12.38"
DEFAULT_LLVM_VER = "18.1.7"
DEFAULT_M4 = "1.4.19"
DEFAULT_MUSL = "1.2.5"
DEFAULT_NAMESERVER = "8.8.8.8"
DEFAULT_PCRE2 = "10.44"
DEFAULT_ROOTFS_BRANCH = "v3.23"
DEFAULT_ROOTFS_SEED = "Alpine"
DEFAULT_ROOTFS_VERSION = "3.23.2"
DEFAULT_SHARDS = "0.18.0"
DEFAULT_SQLITE = "3460000"
DEFAULT_ZLIB = "1.3.1"
SHARDS_CACHE_DIR = "/tmp/.shards-cache"

Constructors

new(workspace : SysrootWorkspace | Nil = nil, architecture : String = DEFAULT_ARCH, seed : String = DEFAULT_ROOTFS_SEED)

Create a sysroot builder in workspace.

Source

Class methods

aliases

Return command aliases handled by the sysroot builder CLI.

Source
help_entries

Describe help output entries for the sysroot builder CLI.

Source
run(args : Array(String), command_name : String) : Int32

Dispatch sysroot builder subcommands by command name.

Source
summary

Summarize the sysroot builder CLI behavior for help output.

Source

Instance methods

bootstrap_repo_dir
Source
bootstrap_source_version
Source
build_plan

Construct a phased build plan. The plan is serialized into the chroot so it can be replayed by the coordinator runner.

Source
cache_dir

Cache directory for checksum metadata.

Source
checksum_dir

Directory for checksum files keyed by package.

Source
host_workdir

Host workspace path for the builder.

Source
inner_rootfs_workspace_dir

Path to the workspace directory inside the inner rootfs.

Source
outer_rootfs_dir

Path to the outer rootfs directory on the host.

Source
packages

Declarative list of upstream sources that should populate the sysroot. Each PackageSpec can carry optional configure flags or a custom build directory name when upstream archives use non-standard layouts.

Source
phase_specs

Define the multi-phase build in an LFS-inspired style:

  1. build a complete sysroot from sources using the selected seed environment
  2. validate the sysroot by using it as the toolchain when assembling a rootfs

Phases:

  • host-setup: populate sources and seed the rootfs from the host.
  • sysroot-from-seed: build the sysroot using tools available in the seed rootfs.
  • rootfs-from-sysroot: build the minimal rootfs using the new sysroot toolchain.
  • system-from-sysroot: build core system packages inside the new rootfs.
  • tools-from-system: build developer tools inside the new rootfs.
  • finalize-rootfs: strip /opt/sysroot and emit the tarball.

Phase namespaces:

  • host: runs on the host before entering any namespace.
  • seed: runs in the seed rootfs (host tools).
  • bq2: runs inside the bq2 rootfs, prefers /usr/bin, and relies on musl's /etc/ld-musl-<arch>.path for runtime lookup.
Source
rootfs_ready?

Return true when a serialized plan exists in the workspace.

Source
seed_rootfs_spec

Build a PackageSpec pointing at the base rootfs tarball for the configured architecture. The checksum URL is derived from the upstream naming convention when available.

Source
sources_dir

Directory where source tarballs are stored.

Source
workdir_for(package : PackageSpec, phase : PhaseSpec) : String

Return the workspace directory that should be used for building package.

Source
workspace
Source
write_plan(plan : BuildPlan = build_plan) : Path

Persist the build plan JSON.

Source

Nested types