DarkForge Toolchain Bootstrap
Cross-compilation toolchain scripts that build the base system from scratch, following the Linux From Scratch (LFS 13.0) methodology with DarkForge-specific customizations.
Overview
These scripts implement LFS Chapters 5-7, adapted for:
- Target: AMD Ryzen 9 9950X3D (Zen 5,
-march=znver5) - Compiler: GCC 15.2.0 (full znver5 support)
- Target triplet:
x86_64-darkforge-linux-gnu
The build produces a self-hosting chroot environment capable of compiling everything else.
Requirements
Environment: Any Linux distribution (x86_64). This does NOT run on macOS or Windows.
The toolchain bootstrap is a cross-compilation step that runs entirely on a Linux host and produces a self-contained chroot targeting the DarkForge hardware.
Tested host distros:
- Arch Linux (recommended)
- Ubuntu 22.04+, Debian 12+
- Fedora 38+
Required packages:
# Arch Linux
sudo pacman -S base-devel wget texinfo
# Ubuntu / Debian
sudo apt install build-essential bison gawk m4 texinfo xz-utils wget
# Fedora
sudo dnf groupinstall "Development Tools" && sudo dnf install texinfo wget
Minimum versions: GCC 12+, GNU Make 4.x, Bash 5.x, Python 3.10+
Disk space: ~20GB for the full toolchain build (sources + build artifacts)
Dedicated partition: You need a separate partition (or loopback image) mounted at $LFS (default: /mnt/darkforge). This becomes the root of the new system.
Host System Verification
# Verify essential tools are present
for cmd in bash gcc g++ make bison gawk m4 texinfo xz wget; do
command -v $cmd >/dev/null && echo "OK: $cmd" || echo "MISSING: $cmd"
done
# Check GCC version (need 12+ for znver4/znver5 support)
gcc --version | head -1
Build Process
Step 1: Set up the environment
export LFS=/mnt/darkforge
# Create and mount your target partition
sudo mkdir -pv $LFS
sudo mount /dev/nvme0n1p3 $LFS # adjust device as needed
# Run the environment setup
sudo bash scripts/000-env-setup.sh
This creates the lfs user, directory structure, and environment variables.
Step 2: Download sources
bash scripts/000a-download-sources.sh
Downloads all ~30 source tarballs to $LFS/sources/.
Step 3: Build the cross-toolchain (Chapter 5)
bash scripts/build-all.sh cross
Builds: binutils (pass 1) → GCC (pass 1) → Linux headers → glibc → libstdc++
Step 4: Build temporary tools (Chapter 6)
bash scripts/build-all.sh temp
Builds 17 packages: m4, ncurses, bash, coreutils, diffutils, file, findutils, gawk, grep, gzip, make, patch, sed, tar, xz, binutils (pass 2), GCC (pass 2).
Step 5: Enter chroot and build native tools (Chapter 7)
sudo bash scripts/023-chroot-setup.sh
# Now inside the chroot:
bash /sources/toolchain-scripts/024-chroot-essentials.sh
bash /sources/toolchain-scripts/025-gettext.sh
# ... through 030-util-linux.sh
bash /sources/toolchain-scripts/031-cleanup.sh
Step 6: Verify
The cleanup script runs a "Hello World" compilation test. If it passes, the toolchain is ready.
Script Inventory
| Script | Phase | Description |
|---|---|---|
000-env-setup.sh |
Setup | Creates directories, lfs user, environment |
000a-download-sources.sh |
Setup | Downloads all source tarballs |
001-binutils-pass1.sh |
Ch.5 | Cross-assembler and linker |
002-gcc-pass1.sh |
Ch.5 | Cross-compiler (C/C++) |
003-linux-headers.sh |
Ch.5 | Linux API headers |
004-glibc.sh |
Ch.5 | GNU C Library (with sanity checks) |
005-libstdcxx.sh |
Ch.5 | C++ standard library |
006-m4.sh – 020-xz.sh |
Ch.6 | Temporary tools (15 packages) |
021-binutils-pass2.sh |
Ch.6 | Native binutils |
022-gcc-pass2.sh |
Ch.6 | Native GCC |
023-chroot-setup.sh |
Ch.7 | Mount virtual filesystems, enter chroot |
024-chroot-essentials.sh |
Ch.7 | Create /etc/passwd, /etc/group, etc. |
025-gettext.sh – 030-util-linux.sh |
Ch.7 | Native chroot tools |
031-cleanup.sh |
Ch.7 | Strip binaries, run exit criteria test |
build-all.sh |
Meta | Master build runner with logging |
Version Manifest
See VERSION_MANIFEST.md for the exact version of every package used, with source URLs and rationale.
Logs
Build logs are saved to logs/<script-name>.log by the master build runner.
Troubleshooting
If a build fails:
- Check the log file in
logs/ - The most common issue is a missing host dependency
- The glibc sanity checks (script 004) are critical — if they fail, the entire toolchain is broken
- GCC pass 1 is the longest build (~4 SBU on the 9950X3D with
-j32)
Repository
git@git.dannyhaslund.dk:danny8632/darkforge.git
Toolchain scripts live in the toolchain/ directory of the main DarkForge repo.