# BTC.sh (Build Tool Chain)
## Version 0.4.0

BTC.sh is a bare-metal, cleanroom toolchain generation engine designed for
independent infrastructure. It produces hardened, microarchitecture-optimized
cross-toolchains across 19 target configurations spanning Intel, AMD, ARM,
MIPS, and Tilera TILE-Gx processors.

The project treats the build process as a forensic exercise: it does not simply
compile code — it instantiates a sovereign build environment in volatile memory,
stamps every resulting binary with an immutable hardware identity, and monitors
the forge's health via integrated thermal and entropy sentinels.

## Cross-Compilation Targets

BTC.sh 0.4.0 supports 19 targets organized into five families. Target selection is
driven by an associative array registry — a table-driven design following PEP
868 and MISRA conventions.

### Intel HEDT / Server (5 targets)

| Target ID         | Microarchitecture   | ISA    | C Library | Description                                      |
|--------------------|----------------------|--------|-----------|--------------------------------------------------|
| `haswell`          | haswell              | AVX2   | glibc     | Intel Haswell (Core i7-4xxx / Xeon E5 v3)       |
| `haswell-ep`       | haswell              | AVX2   | glibc     | Intel Haswell-EP X99 (Xeon E5/E7 v3)            |
| `skylake`          | skylake              | AVX2   | glibc     | Intel Skylake (Core i7-6xxx / Xeon v5)          |
| `skylake-x`        | skylake-avx512       | AVX512 | glibc     | Intel Skylake-X X299 (i9-7xxx / Xeon Scalable)  |
| `skylake-server`   | skylake-server       | AVX512 | glibc     | Intel Skylake-Server (Xeon SP 1st/2nd Gen)       |

### AMD Ryzen / EPYC (4 targets)

| Target ID   | Microarchitecture | ISA    | C Library | Description                              |
|-------------|--------------------|--------|-----------|------------------------------------------|
| `znver1`    | znver1             | AVX2   | glibc     | AMD Zen1 (Ryzen 1000 / EPYC Naples)     |
| `znver2`    | znver2             | AVX2   | glibc     | AMD Zen2 (Ryzen 3000 / EPYC Rome)       |
| `znver3`    | znver3             | AVX2   | glibc     | AMD Zen3 (Ryzen 5000 / EPYC Milan)      |
| `znver4`    | znver4             | AVX512 | glibc     | AMD Zen4 (Ryzen 7000 / EPYC Genoa)      |

### AMD APU (4 targets)

| Target ID  | Microarchitecture | ISA    | C Library | Description                                     |
|------------|--------------------|--------|-----------|-------------------------------------------------|
| `apu-zn1`  | znver1             | AVX2   | glibc     | AMD APU S1 Zen — Raven Ridge (2400GE / 3200GE) |
| `apu-zn2`  | znver1             | AVX2   | glibc     | AMD APU S2 Zen+ — Picasso (3250U / 3500U)      |
| `apu-zn3`  | znver2             | AVX2   | glibc     | AMD APU S3 Zen2 — Renoir (4500U / 4700U)       |
| `apu-zn4`  | znver3             | AVX2   | glibc     | AMD APU S4 Zen3 — Cezanne (5500U / 5700U)      |

### Intel Atom (4 targets)

| Target ID           | Microarchitecture | ISA     | C Library | Description                                                |
|----------------------|--------------------|---------|-----------|------------------------------------------------------------|
| `atom-silvermont`    | silvermont         | SSE4_2  | glibc     | Atom Silvermont — Bay Trail (Z3000 / E38xx series)        |
| `atom-goldmont`      | goldmont           | SSE4_2  | glibc     | Atom Goldmont — Apollo Lake (x5-Z8350 / N4200)            |
| `atom-tremont`       | tremont            | SSE4_2  | glibc     | Atom Tremont — Elkhart Lake (x6000E series)               |
| `atom-sierraforest`  | sierraforest       | SSE4_2  | glibc     | Atom Sierra Forest — x7000RE E-core cluster               |

### Embedded / Non-x86 (2 targets)

| Target ID  | Architecture | Microarchitecture | ISA    | C Library | Description                                         |
|------------|--------------|--------------------|--------|-----------|-----------------------------------------------------|
| `mipselr2` | mipsel       | mips32r2           | MIPS32 | musl      | MIPS32R2 LE o32 (MALTA / embedded routers)          |
| `armv7`    | arm          | armv7-a            | NEON   | musl      | ARMv7-A HF NEON (Cortex-A7/A9/A15, RPi 2/3 32-bit) |
| `tilegx`   | tilegx       | tilegx             | TILE   | musl      | Tilera TILE-Gx72 (mesh VLIW)                         |

## ISA Tier Architecture

Six ISA tiers govern optimization flags. 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 target microarchitecture:

| ISA Tier | Flags                                               |
|----------|-----------------------------------------------------|
| AVX512   | `-mavx512f -mavx512dq -mavx512vl -mavx512bw`       |
| AVX2     | `-mavx2`                                            |
| SSE4_2   | `-msse4.2`                                          |
| NEON     | `-mfpu=neon -mfloat-abi=hard`                       |
| MIPS32   | (per-target: `--with-arch=mips32r2 --with-float=soft`) |
| TILE     | (per-target: `--with-arch=tilegx`)                  |

The SSE4_2 tier exists because Intel Atom and AMD APU low-power cores lack AVX
support entirely.

## Usage

```bash
# Build a cross-toolchain for a specific target
sudo ./BTC.sh <target_id>

# Build a host-optimized native toolchain
sudo ./BTC.sh --native

# List all available targets with descriptions
sudo ./BTC.sh --list
```

## Architectural Pillars

Built to LFS 13.0 stable standards (Binutils 2.46,
GCC 14.2.0, Glibc 2.41, musl 1.2.5). No pre-built binaries — every toolchain
is compiled from source on your hardware.

**Silicon Identity.** Every binary produced by a BTC.sh toolchain includes
an immutable ELF note (`.note.BTC`, note type NT_VERSION) and an extended
filesystem attribute (`user.btc.stamp`) linking the binary to the specific
hardware, toolchain version, and forge environment that created it.

**Volatile Cleanroom.** All compilation occurs in a ramfs mount, ensuring zero
I/O wear on host hardware and a pristine build environment on every invocation.

**Thermal Sentinel.** Integrated telemetry loops prevent thermal runaway and
memory saturation during heavy LTO (Link Time Optimization) phases.

**Forensic Auditing.** Every build creates a verifiable manifest, enabling
traceback of any binary to the exact source tree, configuration, and forge
state that produced it.

**Zero-Trust Deployment.** Mandatory AGPLv3 licensing protects the toolchain
logic from proprietary SaaS capture.

## Host Requirements

- A standard Linux host (Debian, Arch, Fedora, Source Mage, etc.) with a
  working native GCC toolchain.
- Root (EUID 0) is required for ramfs mounting and xattr stamping.
- Sufficient RAM for the ramfs build environment (8 GB minimum recommended
  for x86_64 targets; 4 GB for embedded targets).
- Persistent storage at `/opt/BTC` for logs, release archives, and cached
  source tarballs.

## Licensing

GNU Affero General Public License v3.0 (AGPL-3.0). Per Section 13, the forge
includes an interactive notice at runtime. Network deployment of modified
versions requires providing the Corresponding Source to your users.

## Acknowledgments

Original architecture based on scripts by Charles M. "Chip" Coldwell, Harvard
University. Modern cross-compilation, hardening, and sovereignty features
engineered by Jeremy Anderson dcos.net (2012–2026).