darkforge/docs/CHAPTER8-SCRIPTS.md

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:

# 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)

#!/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

   localedef -i en_US -f UTF-8 en_US.UTF-8
   

   Creates UTF-8 support for the en_US locale.

3. Timezone Setup

   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:

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):

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):

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
• BLFS 12.4 — For optional package details
• DarkForge CLAUDE.md — Project architecture and decisions