# 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:**

```bash
# 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

```bash
# 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

```bash
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
bash scripts/000a-download-sources.sh
```

Downloads all ~30 source tarballs to `$LFS/sources/`.

### Step 3: Build the cross-toolchain (Chapter 5)

```bash
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
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)

```bash
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:

1. Check the log file in `logs/`
2. The most common issue is a missing host dependency
3. The glibc sanity checks (script 004) are critical — if they fail, the entire toolchain is broken
4. 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.