Big script

2026-03-20 15:09:30 +01:00
parent dc2ac2f768
commit a2ca02a856
92 changed files with 5842 additions and 0 deletions
--- a/docs/CHAPTER8-SCRIPTS.md
+++ b/docs/CHAPTER8-SCRIPTS.md
@@ -0,0 +1,231 @@
+# 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