dcosnet
/
BuildToolChain
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
BuildToolChain/btc-quickstart.md

3.1 KiB
Executable File
Raw Blame History

BTC Quickstart — Version 0.4.1

A guide to building your first cross-toolchain with BTC.sh .

1. Prerequisites

Requirement Details
Host OS Any Linux distribution with native GCC (Debian, Arch, Fedora, Source Mage, etc.)
Permissions Root (EUID 0) — required for ramfs mounting and forensic xattr stamping
Storage /opt/BTC — persistent location for logs, golden image tarballs, and source cache
RAM 8 GB minimum for x86_64 targets; 4 GB for ARM/MIPS/TILE targets

2. The Pipeline

executes in four phases:

  1. Probe — Silicon topology is scanned. Thread counts are computed from available RAM to prevent LTO thrashing. The target registry is loaded.
  2. Setup — A volatile cleanroom (ramfs) is provisioned at the configured mount point. Source tarballs are verified against their SHA-256 checksums.
  3. Build — Core components are built sequentially: Binutils → Kernel Headers → GCC Stage 1 → C Library (glibc or musl) → GCC Stage 2 → Kernel. Both GCC stages are configured with --with-arch=<march> and --with-cpu=<march> to default to the target microarchitecture.
  4. Package — The resulting cross-toolchain is compressed into a golden image tarball. A manifest JSON sidecar and forensic ELF stamp are applied.

3. Build a Cross-Toolchain

# List all 19 available targets
sudo ./BTC.sh --list

# Build a cross-toolchain for AMD Zen3 (Ryzen 5000 / EPYC Milan)
sudo ./BTC.sh znver3

# Build for Intel Atom Tremont (Elkhart Lake)
sudo ./BTC.sh atom-tremont

# Build for ARMv7 (Raspberry Pi 2/3 32-bit)
sudo ./BTC.sh armv7

# Build a host-optimized native toolchain
sudo ./BTC.sh --native

4. Verify the Golden Image

After a successful build, the golden image tarball and its manifest are written to /opt/BTC/releases/:

# List available golden images
ls -la /opt/BTC/releases/

# Inspect the manifest
cat /opt/BTC/releases/DCOSNET-amd-znver3-AVX2-CROSS-toolchain-manifest.json

The manifest contains structured metadata: target ID, architecture, C library, microarchitecture, ISA tier, cross-compiler triple, and build timestamps.

5. Forensic Stamp Verification

Any binary compiled with a BTC-built toolchain carries the .note.BTC ELF section. Verify it:

# Read the ELF note
readelf -n /path/to/binary | grep -A5 BTC

# Read the xattr stamp
getfattr -d user.btc.stamp /path/to/binary

6. Integration with Sorcery-Go and Fester

BTC golden images are automatically detected by both Sorcery-Go (pkg/toolchain/btc.go) and Fester (backend/toolchain/btc.py). Place the extracted toolchain at /opt/BTC/<SYS_LABEL>/ and the integration layer probes the manifest, configures build environment variables (CC, CXX, CFLAGS, LDFLAGS), and verifies stamps on build outputs.

7. Source Cache

BTC.sh caches downloaded source tarballs in /opt/BTC/sources/. If a tarball is already present and its checksum matches, it is not re-downloaded. Keep the cache directory intact between builds to avoid unnecessary load on upstream mirrors.