BuildToolChain/NOTES.md

BTC.sh — Development Notes

Provenance

BTC.sh (Build Tool Chain) is a clean, cleanroom toolchain generation engine derived from the cross-LFS methodology. The original architecture was based on buildchain.sh by Charles M. "Chip" Coldwell at Harvard University:

http://frank.harvard.edu/~coldwell/toolchain/buildchain.sh

The script has been substantially rewritten and extended by the DCOSNET project (2012–2026). All modern cross-compilation, forensic stamping, and thermal sentinel features are original work.

Design Principles

Target-Host Separation

The host machine is always an average x86_64 system. Target architectures are cross-compiled via sysroot, following the CLFS (Cross Linux From Scratch) and Buildroot target configuration methodology. The host compiler is never used to produce target binaries — every target has its own dedicated cross-toolchain.

Table-Driven Target Registry

All 22 targets are defined in a single associative array (BTC_TARGETS[]). Each entry specifies eleven fields in pipe-delimited format:

arch|multilib_arch|march|ISA|abi|libc|endian|family|description|min_kernel|gcc_extra

This design follows PEP 868 (table-driven configuration) and MISRA-C (separation of data from logic). Adding a new target requires one array assignment — no control-flow changes.

Volatile Cleanroom Compilation

All compilation occurs in a ramfs mount. This provides zero I/O wear on host storage and guarantees a pristine build environment on every invocation. The ramfs is mounted at the start of the build phase and unmounted after the toolchain is packaged into its golden image tarball.

Silicon Identity (Forensic Stamping)

Every binary produced by a BTC-built toolchain carries two immutable identifiers:

1. ELF .note.BTC section — note name "DCOSNET", note type 0xB7C (vendor-specific), containing a pipe-delimited string with org, kernel version, target ID, march, ISA, sys_label, build stage, signature tier, and the active signature token.
2. Extended attributes (xattr) — four attributes written to the binary file:
   • user.btc.identity — BTC-<SYS_LABEL>-<v_linux>-<sig_tier>
   • user.btc.hash — SHA-256 of the stamped binary
   • user.btc.sig.tier — poly | tpm | cluster
   • user.btc.sig.token — the active signature token

These stamps allow any binary to be traced back to the exact build environment, toolchain version, and source tree that produced it.

Dual C Library Strategy

• x86_64 targets: glibc — full POSIX compatibility for workstation and server deployments.
• ARM, MIPS, TILE targets: musl — lightweight, statically-linkable C library suitable for embedded cross-compilation and minimal rootfs images.

ISA Tiers

BTC.sh classifies targets by instruction set capability. The ISA tier determines the optimization flags passed to GCC:

ISA Tier	Targets	Flags
AVX512	skylake-x, skylake-server, znver4	-mavx512f -mavx512dq -mavx512vl -mavx512bw
AVX2	haswell, haswell-ep, skylake, znver1–3,	-mavx2
	apu-zn1–zn4
SSE4_2	atom-silvermont, atom-goldmont,	-msse4.2
	atom-tremont, atom-sierraforest
NEON	armv7	-mfpu=neon -mfloat-abi=hard
MIPS32	mipselr2	(march set per target)
TILE	tilegx	(arch set per target)

The SSE4_2 tier exists because Intel Atom and AMD APU low-power cores lack AVX support. GCC is configured with --with-arch=<march> in both Stage 1 and Stage 2 to ensure the cross-compiler defaults to the correct target microarchitecture. --with-cpu=<march> is added for x86_64 targets only — ARM, MIPS, and TILE backends reject --with-cpu=<arch> (they want a CPU name like cortex-a9, not an architecture name like armv7-a) and instead carry their per-target --with-* hints via BTC_T_GCC_EXTRA.

LFS Base Standards

BTC.sh follows Linux From Scratch 13.0 stable (released 2024-09-01), bumped forward to the latest point releases actually downloadable from upstream mirrors as of v0.4.2:

• Binutils 2.46.1 (LFS 13.0 ships 2.46)
• GCC 15.3.0 (LFS 13.0 ships 14.2.0; bumped to 15.3.0 for znver4 / sierraforest march support and GCC 15 stricter const-correctness — requires -Wno-error for libxcrypt 4.5.2, which f_libxcrypt() already passes)
• Glibc 2.43 (LFS 13.0 ships 2.41)
• musl 1.2.6 (LFS 13.0 ships 1.2.5)
• Linux 7.1.7 (latest 7.1.x point release; LFS 13.0 ships 6.10)
• Tile-Gx override: Linux 5.4.302 LTS + GCC 10.3.0 (mainline dropped tile in Linux 5.9 / GCC 12)

C Library Selection Rationale

• glibc is used for x86_64 targets (including Atom and APU) because deployment environments typically have full development infrastructure, large rootfs, and require maximum POSIX compatibility.
• musl is used for ARM, MIPS, and TILE targets where disk space is constrained and static linking is frequently required for embedded deployment.

Research References

The following resources informed the BTC.sh architecture. They are listed for attribution purposes and are not directly incorporated into the script:

• Cross Linux From Scratch 1.0.0 — http://cross-lfs.org/view/1.0.0/x86_64-64/
• Kernel header installation — Documentation/make/headers_install.txt
• GNU toolchain / glibc building — devpit.org, chschneider.eu/linux/tfs/
• GNU Embedded Programming — www.bravegnu.org/gnu-eprog/
• ttylinux xbuildroot scripts (CLFS methodology reference)
• Source Mage GNU/Linux — relevant spell build logic
• Chip Coldwell's buildchain.sh — http://frank.harvard.edu/~coldwell/toolchain

Source Cache Policy

BTC.sh caches all downloaded source tarballs locally under /opt/BTC/src/ to avoid placing unnecessary load on upstream hosting infrastructure. Automated bulk downloads should be rate-limited and sources retained after initial fetch. The cache is reused across builds; the integrity check in _archive_sane() automatically discards and re-fetches corrupted archives on the next run.

License

BTC.sh is released under the GNU Affero General Public License v3.0 (AGPL-3.0). Per Section 13, the build includes an interactive notice at runtime. If you modify and provide this build as a network service, you are legally obligated to provide the Corresponding Source to your users.