# LFS Chapter 8 Build Scripts

This directory contains 13 build scripts that construct the complete base system for DarkForge Linux inside a chroot environment.

## Quick Reference

Run these scripts in sequence **inside the chroot**:

```bash
cd /sources/toolchain-scripts

# Foundation (required before anything else)
./101-man-pages.sh
./102-iana-etc.sh
./103-glibc.sh          # CRITICAL — System transitions to native here

# Compression libraries
./104-zlib.sh
./105-bzip2.sh
./106-xz.sh
./107-lz4.sh
./108-zstd.sh

# Utilities and build tools
./109-file.sh
./110-readline.sh
./111-m4.sh
./112-bc.sh
./113-flex.sh
```

## Scripts

### 101-man-pages.sh
- **Package:** Man-Pages 6.12
- **Purpose:** System call and library function documentation
- **LFS Reference:** Chapter 8.3
- **Time:** < 1 minute (just installation, no compilation)
- **Critical deps:** None

### 102-iana-etc.sh
- **Package:** IANA-Etc 20250306
- **Purpose:** Protocol and service name definitions (`/etc/services`, `/etc/protocols`)
- **LFS Reference:** Chapter 8.4
- **Time:** < 1 minute (just installation)
- **Critical deps:** None

### 103-glibc.sh ⭐ CRITICAL
- **Package:** Glibc 2.43
- **Purpose:** The GNU C Library (complete native version)
- **LFS Reference:** Chapter 8.5
- **Time:** 5-10 minutes
- **Key additions:**
  - Applies `glibc-fhs-1.patch` for FHS compliance
  - Generates `en_US.UTF-8` locale
  - Sets up timezone data (defaults to UTC)
  - Creates `/etc/nsswitch.conf`
  - Runs comprehensive sanity checks
- **Critical deps:** Previous toolchain (binutils, gcc cross-compiled), Linux headers
- **Post-build verification:**
  ```bash
  /usr/lib/libc.so.6 exists
  ldd works
  Simple C program executes
  ```

### 104-zlib.sh
- **Package:** Zlib 1.3.2
- **Purpose:** Compression library (critical for many tools)
- **LFS Reference:** Chapter 8.6
- **Time:** < 2 minutes
- **Includes:** `make check` test suite
- **Critical deps:** Glibc (103)

### 105-bzip2.sh
- **Package:** Bzip2 1.0.8
- **Purpose:** Bzip2 compression utility and library
- **LFS Reference:** Chapter 8.7
- **Time:** < 2 minutes
- **Special:** Applies `bzip2-1.0.8-install_docs-1.patch` for documentation
- **Non-standard build:** Uses `Makefile-libbz2_so` for dynamic library
- **Critical deps:** Glibc (103)

### 106-xz.sh
- **Package:** XZ Utils 5.8.1
- **Purpose:** LZMA compression utilities (needed for `.tar.xz` files)
- **LFS Reference:** Chapter 8.8
- **Time:** 2-3 minutes
- **Note:** Handles both `.tar.gz` and `.tar.xz` tarball formats
- **Critical deps:** Glibc (103)

### 107-lz4.sh
- **Package:** LZ4 1.10.0
- **Purpose:** Fast LZ4 compression library and tools
- **LFS Reference:** Chapter 8.9
- **Time:** < 1 minute
- **Non-standard:** Custom Makefile (not autoconf)
- **Critical deps:** Glibc (103)

### 108-zstd.sh
- **Package:** Zstd 1.5.7
- **Purpose:** Zstandard compression (modern compression algorithm)
- **LFS Reference:** Chapter 8.10
- **Time:** 3-5 minutes (heavy optimization)
- **Non-standard:** Custom Makefile (not autoconf)
- **Critical deps:** Glibc (103)

### 109-file.sh
- **Package:** File 5.47
- **Purpose:** File type detection command and libmagic library
- **LFS Reference:** Chapter 8.11
- **Time:** < 2 minutes
- **Includes:** `make check` test suite
- **Critical deps:** Glibc (103), Zlib (104)

### 110-readline.sh
- **Package:** Readline 8.3
- **Purpose:** Command-line editing and history library
- **LFS Reference:** Chapter 8.12
- **Time:** < 2 minutes
- **Includes:** Documentation installation
- **Links with:** ncurses library
- **Critical deps:** Glibc (103), ncurses (from earlier phases)

### 111-m4.sh
- **Package:** M4 1.4.21
- **Purpose:** Macro processing language (required for autoconf/automake)
- **LFS Reference:** Chapter 8.14
- **Time:** < 2 minutes
- **Includes:** `make check` test suite
- **Critical deps:** Glibc (103)

### 112-bc.sh
- **Package:** Bc 7.0.3
- **Purpose:** Arbitrary-precision calculator
- **LFS Reference:** Chapter 8.15
- **Time:** 1-2 minutes
- **Non-standard:** Custom configure script (not typical GNU autoconf)
- **Includes:** `make test` suite
- **Critical deps:** Glibc (103)

### 113-flex.sh
- **Package:** Flex 2.6.4
- **Purpose:** Lexical scanner generator (replaces older 'lex')
- **LFS Reference:** Chapter 8.16
- **Time:** 2-3 minutes
- **Includes:** `make check` test suite
- **Special:** Creates `/usr/bin/lex` symlink for legacy compatibility
- **Critical deps:** Glibc (103)

## Environment

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

```bash
# AMD Zen 5 specific compilation flags
CFLAGS="-march=znver5 -O2 -pipe -fomit-frame-pointer"
CXXFLAGS="${CFLAGS}"
LDFLAGS="-Wl,-O1,--as-needed"
MAKEFLAGS="-j32"                      # Full CPU utilization (16 cores × 2)

# Helper functions
pkg_extract(TARBALL)   # Extract and cd into source dir
pkg_cleanup(DIRNAME)   # Remove source directory after build
```

## Troubleshooting

### General Issues

1. **"Permission denied" when running script**
   ```bash
   chmod +x 10X-*.sh
   ```

2. **"file not found" for tarball**
   - Ensure `/sources/` contains all tarballs
   - Check `100-download-phase3.sh` for correct filenames

3. **"patch does not apply"**
   - Verify you're in the correct directory after extraction
   - Check patch is in `/sources/` with correct filename

### Build Failures

- All scripts use `set -euo pipefail`, so they stop immediately on errors
- Check the error output for missing dependencies or configuration issues
- Ensure previous scripts completed successfully before running the next one

### Most Common Issue

**Glibc (103) fails** — This is usually because:
1. The FHS patch didn't apply correctly
2. Linux headers are missing from `/usr/include/`
3. Previous cross-compiled toolchain is broken

Verify all Phase 0-2 scripts ran successfully before attempting Phase 3.

## Documentation

For detailed information about each package and the build process, see:
- `/sessions/awesome-gallant-bell/mnt/lfs_auto_install/docs/CHAPTER8-SCRIPTS.md`

For the complete LFS reference:
- `/sessions/awesome-gallant-bell/mnt/lfs_auto_install/reference/LFS-BOOK-r13.0-4-NOCHUNKS.html`

## Statistics

- **Total scripts:** 13
- **Total size:** ~20 KB
- **Estimated total build time:** 30-45 minutes (on 16-core CPU)
- **Line of code:** ~450 lines (across all scripts)

## Next Steps

After these 13 scripts complete successfully:

1. Continue with Phase 3 remaining packages (Chapter 8.17+)
2. Build the Linux kernel (Phase 4)
3. Configure init system (sysvinit) (Phase 5)
4. Install desktop environment (dwl/Wayland) (Phase 6+)

---

**Created:** 2026-03-20
**Target:** DarkForge Linux (AMD Zen 5 build)
**Reference:** LFS 13.0 Chapter 8