# 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.