232 lines
8.0 KiB
Markdown
232 lines
8.0 KiB
Markdown
# 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
|