# BTC Quickstart — Version 0.4.1

A guide to building your first cross-toolchain with BTC.sh .

## 1. Prerequisites

| Requirement | Details |
|-------------|---------|
| Host OS     | Any Linux distribution with native GCC (Debian, Arch, Fedora, Source Mage, etc.) |
| Permissions | Root (EUID 0) — required for ramfs mounting and forensic xattr stamping |
| Storage     | `/opt/BTC` — persistent location for logs, golden image tarballs, and source cache |
| RAM         | 8 GB minimum for x86_64 targets; 4 GB for ARM/MIPS/TILE targets |

## 2. The Pipeline

executes in four phases:

1. **Probe** — Silicon topology is scanned. Thread counts are computed from
   available RAM to prevent LTO thrashing. The target registry is loaded.
2. **Setup** — A volatile cleanroom (ramfs) is provisioned at the configured
   mount point. Source tarballs are verified against their SHA-256 checksums.
3. **Build** — Core components are built sequentially:
   Binutils → Kernel Headers → GCC Stage 1 → C Library (glibc or musl) → GCC Stage 2 → Kernel.
   Both GCC stages are configured with `--with-arch=<march>` and `--with-cpu=<march>`
   to default to the target microarchitecture.
4. **Package** — The resulting cross-toolchain is compressed into a golden
   image tarball. A manifest JSON sidecar and forensic ELF stamp are applied.

## 3. Build a Cross-Toolchain

```bash
# List all 19 available targets
sudo ./BTC.sh --list

# Build a cross-toolchain for AMD Zen3 (Ryzen 5000 / EPYC Milan)
sudo ./BTC.sh znver3

# Build for Intel Atom Tremont (Elkhart Lake)
sudo ./BTC.sh atom-tremont

# Build for ARMv7 (Raspberry Pi 2/3 32-bit)
sudo ./BTC.sh armv7

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

## 4. Verify the Golden Image

After a successful build, the golden image tarball and its manifest are written
to `/opt/BTC/releases/`:

```bash
# List available golden images
ls -la /opt/BTC/releases/

# Inspect the manifest
cat /opt/BTC/releases/DCOSNET-amd-znver3-AVX2-CROSS-toolchain-manifest.json
```

The manifest contains structured metadata: target ID, architecture, C library,
microarchitecture, ISA tier, cross-compiler triple, and build timestamps.

## 5. Forensic Stamp Verification

Any binary compiled with a BTC-built toolchain carries the `.note.BTC` ELF
section. Verify it:

```bash
# Read the ELF note
readelf -n /path/to/binary | grep -A5 BTC

# Read the xattr stamp
getfattr -d user.btc.stamp /path/to/binary
```

## 6. Integration with Sorcery-Go and Fester

BTC golden images are automatically detected by both Sorcery-Go
(`pkg/toolchain/btc.go`) and Fester (`backend/toolchain/btc.py`). Place the
extracted toolchain at `/opt/BTC/<SYS_LABEL>/` and the integration layer
probes the manifest, configures build environment variables (CC, CXX, CFLAGS,
LDFLAGS), and verifies stamps on build outputs.

## 7. Source Cache

BTC.sh caches downloaded source tarballs in `/opt/BTC/sources/`. If a tarball
is already present and its checksum matches, it is not re-downloaded. Keep the
cache directory intact between builds to avoid unnecessary load on upstream
mirrors.