91 lines
3.6 KiB
Markdown
Executable File
91 lines
3.6 KiB
Markdown
Executable File
# Toolchain Specification
|
|
|
|
## 1. Sovereign Toolchains
|
|
|
|
The Coven does not download pre-built GCC/LLVM binaries. Each admin maintains
|
|
their own toolchains, or forges them with BTC.sh. Toolchains are stored under
|
|
`/opt/sorcery-go/toolchains/<triple>/` (manual) or `/opt/BTC/<SYS_LABEL>/`
|
|
(BTC.sh golden images). The Sandbox `AttachToolchain` bind-mounts the requested
|
|
toolchain read-only into the build namespace.
|
|
|
|
## 2. BTC.sh Integration
|
|
|
|
Sorcery-Go integrates with BTC.sh for cross-compilation across 19 target
|
|
architectures. The `pkg/toolchain/btc.go` module probes for golden images,
|
|
parses their manifest JSON sidecars, and configures the build environment.
|
|
|
|
### Supported Targets
|
|
|
|
| Family | Targets |
|
|
|------------------|----------------------------------------------------------------|
|
|
| Intel HEDT/Server| haswell, haswell-ep, skylake, skylake-x, skylake-server |
|
|
| AMD Ryzen/EPYC | znver1, znver2, znver3, znver4 |
|
|
| AMD APU | apu-zn1, apu-zn2, apu-zn3, apu-zn4 |
|
|
| Intel Atom | atom-silvermont, atom-goldmont, atom-tremont, atom-sierraforest|
|
|
| Embedded | mipselr2, armv7, tilegx |
|
|
|
|
### ISA Tiers
|
|
|
|
| ISA Tier | Flags |
|
|
|----------|-----------------------------------------------------|
|
|
| AVX512 | `-mavx512f -mavx512dq -mavx512vl -mavx512bw` |
|
|
| AVX2 | `-mavx2` |
|
|
| SSE4_2 | `-msse4.2` |
|
|
| NEON | `-mfpu=neon -mfloat-abi=hard` |
|
|
| MIPS32 | (per-target architecture) |
|
|
| TILE | (per-target architecture) |
|
|
|
|
## 3. Required Specs (Manual Toolchains)
|
|
|
|
```markdown
|
|
# Toolchain: aarch64-linux-musl
|
|
|
|
## Specifications
|
|
- **Version:** GCC 15.1.0 / Binutils 2.44
|
|
- **C Library:** musl 1.2.5
|
|
- **Optimizations:** `-O3 -flto -march=armv8-a`
|
|
- **Hardening:** `-fstack-protector-all -pie -fPIE -D_FORTIFY_SOURCE=2`
|
|
|
|
## Essence Compatibility
|
|
- **Min Engine Version:** 1.0.2
|
|
- **Supported Targets:** Generic-ARM64, Pine64, RPi5
|
|
|
|
## Validation
|
|
- **Validator Pass:** true
|
|
- **Smoke Test:** Hello-World compiled, ldd reports "not a dynamic executable"
|
|
- **Has SSP:** true
|
|
- **Has PIE:** true
|
|
```
|
|
|
|
## 4. Validation Pipeline
|
|
|
|
Every toolchain must pass `pkg/toolchain.Validate` before it can forge
|
|
production Essences:
|
|
|
|
| Check | Method |
|
|
|------------------------|---------------------------------------------------|
|
|
| Arch detection | Parse `gcc -v` output for triple |
|
|
| Stack Smashing Protection | Inspect for `--enable-default-ssp` |
|
|
| PIE | Inspect for `--enable-default-pie` |
|
|
| LTO | Inspect for `--with-default-libstdcxx-abi=lto` |
|
|
| Smoke test | Compile `int main(){}` with `-fstack-protector-all -pie` |
|
|
|
|
If `Validate()` returns `Report.Passed = false`, the Cauldron refuses to
|
|
attach the toolchain and the WebUI flags it in the Toolchain Lab view.
|
|
|
|
## 5. Per-Spell Overrides
|
|
|
|
Some spells (kernel, glibc) need a different toolchain than the default.
|
|
The WebUI lets the admin attach an override per spell:
|
|
|
|
```yaml
|
|
spell: linux
|
|
toolchain_override: /opt/sorcery-go/toolchains/x86_64-linux-gnu-gcc-14
|
|
```
|
|
|
|
## 6. Fleet Re-Forge
|
|
|
|
When a toolchain is updated, the WebUI's Fleet Re-Forge button flags
|
|
every Essence built with the old version and re-queues them for the
|
|
Cauldron. This ensures the entire Coven runs code compiled with the latest
|
|
toolchain. |