127 lines
5.6 KiB
Markdown
Executable File
127 lines
5.6 KiB
Markdown
Executable File
# 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 19 targets are defined in a single associative array
|
||
(`BTC_TARGETS[]`). Each entry specifies ten 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 "BTC", note type 0xB7C (vendor),
|
||
containing a pipe-delimited string with org, version, target, march, ISA,
|
||
and a bare hex SHA-256 hash of the source tarball.
|
||
2. **Extended attributes (xattr)** — the same stamp data is written to
|
||
`user.btc.stamp` on the binary file.
|
||
|
||
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>` and
|
||
`--with-cpu=<march>` in both Stage 1 and Stage 2 to ensure the cross-compiler
|
||
defaults to the correct target microarchitecture.
|
||
|
||
## LFS Base Standards
|
||
|
||
BTC.sh follows Linux From Scratch 13.0 stable (released 2024-09-01):
|
||
|
||
- Binutils 2.46
|
||
- GCC 14.2.0
|
||
- Glibc 2.41
|
||
- musl 1.2.5
|
||
- Linux kernel headers (matched to target `min_kernel`)
|
||
|
||
## 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 to avoid placing
|
||
unnecessary load on upstream hosting infrastructure. Automated bulk downloads
|
||
should be rate-limited and sources retained after initial fetch.
|
||
|
||
## 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. |