92 lines
3.3 KiB
Markdown
92 lines
3.3 KiB
Markdown
# BTC Quickstart — Version 0.4.2
|
|
|
|
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>`
|
|
for x86_64 targets only) 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 22 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
|
|
directly to `/opt/BTC/` (the manifest uses the `${SYS_LABEL}-manifest.json`
|
|
naming convention; the golden image uses `${SYS_LABEL}-toolchain-golden.tar.xz`):
|
|
|
|
```bash
|
|
# List available golden images
|
|
ls -la /opt/BTC/*-toolchain-golden.tar.xz /opt/BTC/*-manifest.json
|
|
|
|
# Inspect the manifest
|
|
cat /opt/BTC/DCOSNET-AMD-ZNVER3-AVX2-CROSS-manifest.json
|
|
```
|
|
|
|
The manifest contains structured metadata: target ID, architecture, C library,
|
|
microarchitecture, ISA tier, cross-compiler triple, signature tier, and build
|
|
configuration flags.
|
|
|
|
## 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 DCOSNET
|
|
|
|
# Read the four xattr stamps
|
|
getfattr -d user.btc.identity,user.btc.hash,user.btc.sig.tier,user.btc.sig.token /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/src/`. If a tarball
|
|
is already present and its integrity check passes, it is not re-downloaded.
|
|
Keep the cache directory intact between builds to avoid unnecessary load on
|
|
upstream mirrors. |