# LFS Chapter 8 Build Scripts — DarkForge Linux Phase 3

**Created:** 2026-03-20
**Target System:** AMD Ryzen 9 9950X3D (Zen 5) with RTX 5090, 96GB RAM
**Reference:** LFS 13.0 Chapter 8 (Building the LFS System)

## Overview

These 13 shell scripts implement LFS 13.0 Chapter 8, building the complete base system inside a chroot environment. Each script is an atomic, testable build step designed to run sequentially and independently.

### Key Features

- **Hardware-specific compilation flags** — All scripts inherit Zen 5 optimization flags from `100-chroot-env.sh`
- **Exact LFS 13.0 build commands** — Every configure/make/install step follows the book exactly
- **Comprehensive error handling** — `set -euo pipefail` ensures builds fail fast on errors
- **Sanity checks and verification** — Each script includes post-build tests to ensure correctness
- **Package version alignment** — Versions match the project's `100-download-phase3.sh`
- **Proper cleanup** — Source files are removed after installation using `pkg_cleanup()`

## Script List (Execution Order)

### Phase 3.1 — System Foundation

| # | Name | Package | Version | LFS Section | Size |
|---|------|---------|---------|-------------|------|
| 101 | man-pages.sh | Man-Pages | 6.12 | §8.3 | 992 B |
| 102 | iana-etc.sh | IANA-Etc | 20250306 | §8.4 | 991 B |
| **103** | **glibc.sh** | **Glibc** | **2.43** | **§8.5** | **4.8K** |

**103-glibc.sh is CRITICAL** — This is where the system transitions from cross-compiled to fully native. All subsequent builds link against this glibc.

**Key additions in 103:**
- FHS patch applied (`glibc-fhs-1.patch`)
- Locale generation (at minimum: `en_US.UTF-8`)
- Timezone data setup with UTC default
- `/etc/nsswitch.conf` creation
- Comprehensive sanity checks

### Phase 3.2 — Compression Libraries

| # | Name | Package | Version | LFS Section | Size |
|---|------|---------|---------|-------------|------|
| 104 | zlib.sh | Zlib | 1.3.2 | §8.6 | 1.3K |
| 105 | bzip2.sh | Bzip2 | 1.0.8 | §8.7 | 1.8K |
| 106 | xz.sh | XZ | 5.8.1 | §8.8 | 1.7K |
| 107 | lz4.sh | LZ4 | 1.10.0 | §8.9 | 1.4K |
| 108 | zstd.sh | Zstd | 1.5.7 | §8.10 | 1.5K |

**Notes:**
- 104 (zlib) tests installed libraries with `make check`
- 105 (bzip2) applies `bzip2-1.0.8-install_docs-1.patch` for documentation
- 106 (xz) handles alternate tarball naming (`.tar.gz` vs `.tar.xz`)
- 107 (lz4) and 108 (zstd) use custom Makefiles (not autoconf)

### Phase 3.3 — Utilities and Build Tools

| # | Name | Package | Version | LFS Section | Size |
|---|------|---------|---------|-------------|------|
| 109 | file.sh | File | 5.47 | §8.11 | 1.5K |
| 110 | readline.sh | Readline | 8.3 | §8.12 | 1.6K |
| 111 | m4.sh | M4 | 1.4.21 | §8.14 | 1.3K |
| 112 | bc.sh | Bc | 7.0.3 | §8.15 | 1.6K |
| 113 | flex.sh | Flex | 2.6.4 | §8.16 | 1.8K |

**Notes:**
- 109 (file) includes libmagic for file type detection
- 110 (readline) uses ncurses and includes documentation
- 111 (m4) is a macro processor (dependency for autoconf/automake)
- 112 (bc) uses custom configure script (non-standard)
- 113 (flex) creates `lex` symlink for legacy tool compatibility

## Build Environment

All scripts source `/sources/toolchain-scripts/100-chroot-env.sh`, which provides:

```bash
# Hardware-specific compiler flags for AMD Zen 5 (Ryzen 9 9950X3D)
export CFLAGS="-march=znver5 -O2 -pipe -fomit-frame-pointer"
export CXXFLAGS="${CFLAGS}"
export LDFLAGS="-Wl,-O1,--as-needed"
export MAKEFLAGS="-j32"                    # 32 threads (16 cores × 2)

# Standard paths
export SRCDIR="/sources"
export SCRIPTS="/sources/toolchain-scripts"

# Helper functions
pkg_extract()   # Extracts tarball and changes into directory
pkg_cleanup()   # Removes source directory after build
```

## Execution Model

### Design Pattern (Every Script)

```bash
#!/bin/bash
set -euo pipefail
source /sources/toolchain-scripts/100-chroot-env.sh

PACKAGE="name"
VERSION="x.y.z"

echo "=== Building ${PACKAGE}-${VERSION} (Phase 3) ==="

# 1. Extract
pkg_extract "${PACKAGE}-${VERSION}.tar.xz"
cd "${PACKAGE}-${VERSION}"

# 2. Patch (if needed)
patch -Np1 -i ../package.patch

# 3. Configure
./configure --prefix=/usr [options]

# 4. Build
make

# 5. Test (optional but recommended)
make check

# 6. Install
make install

# 7. Verify
test -x /usr/bin/binary && echo "PASS"

# 8. Cleanup
pkg_cleanup "${PACKAGE}-${VERSION}"
echo "=== ${PACKAGE}-${VERSION} complete ==="
```

### Execution Context

These scripts run **inside a chroot environment**, where:
- Root filesystem (`/`) = `/mnt/darkforge/` on the host
- `/sources/` is mounted and contains tarballs
- `/sources/toolchain-scripts/` contains helper scripts
- Previous toolchain (binutils, gcc, glibc cross-compiled) is available

### Prerequisites

Before running these scripts:
1. Chroot environment must be set up (see Phase 0-2 scripts)
2. Linux kernel headers installed in `/usr/include/`
3. Cross-compiled toolchain (binutils, gcc, glibc) in place
4. Source tarballs in `/sources/`
5. All required patches in `/sources/`

## Key Implementation Details

### Glibc (103-glibc.sh) — The Critical Step

This is the most important script. Key points:

1. **FHS Patch** — Ensures `/usr/sbin` placement of tools
2. **Locale Generation**
   ```bash
   localedef -i en_US -f UTF-8 en_US.UTF-8
   ```
   Creates UTF-8 support for the en_US locale.

3. **Timezone Setup**
   ```bash
   ln -sfv ../usr/share/zoneinfo/UTC /etc/localtime
   ```
   Defaults to UTC; can be overridden during final system installation.

4. **NSS Configuration** — Creates `/etc/nsswitch.conf` for name service lookups
5. **Sanity Checks** — Verifies libc.so.6, ldd functionality, and basic C program execution

### Bzip2 (105-bzip2.sh) — Non-standard Build

Unlike most packages, bzip2 uses a Makefile instead of autoconf:
```bash
make -f Makefile-libbz2_so    # Build shared library version
make                           # Build static version
make install PREFIX=/usr       # Install both
```

The patch `bzip2-1.0.8-install_docs-1.patch` ensures documentation is installed.

### Flex (113-flex.sh) — Build Tool Compatibility

Creates a symlink for legacy `lex` tool (which flex replaces):
```bash
ln -sv flex /usr/bin/lex
```

Ensures compatibility with scripts that expect the older lexical scanner interface.

## Version Justification

All versions are taken from the project's `100-download-phase3.sh` script and represent:
- **Latest stable releases** as of the download script's date
- **Verified compatibility** with other packages in Phase 3
- **Cross-checked against LFS 13.0** for correctness

## Testing Strategy

Each script includes:
1. **Post-install verification** — Does the binary exist and is it executable?
2. **Functional tests** — Simple sanity tests (where applicable)
3. **Error catching** — `set -euo pipefail` ensures failures are fatal

Example (from M4):
```bash
echo "define(HELLO, Hello World)" | /usr/bin/m4 | grep -q "Hello World"
```

## Future Phases

After these 13 scripts, Phase 3 continues with:
- **Phase 3.4** — System utilities (grep, sed, tar, etc.)
- **Phase 3.5** — More build tools (autoconf, automake, libtool, meson, cmake, ninja)
- **Phase 3.6** — Security (openssl, shadow, eudev)
- **Phase 3.7** — Kernel build and installation
- **Phase 3.8** — Final system configuration (fstab, rc.conf, inittab)

## Notes for Maintainers

1. **Patch updates** — If any patch is updated upstream, verify compatibility before rebuilding
2. **Version changes** — If a package version needs updating, update both the script AND `100-download-phase3.sh`
3. **Compiler flags** — The Zen 5 flags in `100-chroot-env.sh` apply to all scripts. Per-package overrides can be made by setting `CFLAGS`/`CXXFLAGS` before the configure step.
4. **Testing** — Each script can be run independently (if dependencies are met) for testing or debugging.

## References

- [LFS 13.0 Chapter 8](https://www.linuxfromscratch.org/lfs/view/13.0/chapter08/)
- [BLFS 12.4](https://www.linuxfromscratch.org/blfs/) — For optional package details
- DarkForge CLAUDE.md — Project architecture and decisions