90 lines
3.1 KiB
Markdown
Executable File
90 lines
3.1 KiB
Markdown
Executable File
# BTC Quickstart — Version 0.4.0
|
|
|
|
A guide to building your first cross-toolchain with the BTC Sovereign Forge.
|
|
|
|
## 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 Forge Pipeline
|
|
|
|
The forge 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. **Forge** — 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-forged 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. |