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