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

3.3 KiB
Raw Blame History

BTC Quickstart — Version 0.4.2

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> for x86_64 targets only) 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 22 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 directly to /opt/BTC/ (the manifest uses the ${SYS_LABEL}-manifest.json naming convention; the golden image uses ${SYS_LABEL}-toolchain-golden.tar.xz):

# List available golden images
ls -la /opt/BTC/*-toolchain-golden.tar.xz /opt/BTC/*-manifest.json

# Inspect the manifest
cat /opt/BTC/DCOSNET-AMD-ZNVER3-AVX2-CROSS-manifest.json

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

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 DCOSNET

# Read the four xattr stamps
getfattr -d user.btc.identity,user.btc.hash,user.btc.sig.tier,user.btc.sig.token /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/src/. If a tarball is already present and its integrity check passes, it is not re-downloaded. Keep the cache directory intact between builds to avoid unnecessary load on upstream mirrors.