darkforge/README.md

# DarkForge Linux


A custom, from-scratch Linux distribution built for one machine, one user — optimized ruthlessly for gaming and development.

## Target Hardware

| Component | Model |
|-----------|-------|
| CPU | AMD Ryzen 9 9950X3D (Zen 5, 16C/32T, 3D V-Cache) |
| RAM | Corsair Vengeance DDR5-6000 96GB CL30 (2×48GB) |
| Storage | Samsung 9100 PRO 2TB NVMe (PCIe 5.0 x4) |
| GPU | ASUS GeForce RTX 5090 ROG Astral LC OC 32GB GDDR7 |
| Motherboard | ASUS ROG CROSSHAIR X870E HERO |

## Architecture

DarkForge uses a minimal, transparent stack with no systemd:

- **Init:** SysVinit + custom rc.d scripts
- **Device manager:** eudev (no systemd dependency)
- **Boot:** EFISTUB — the kernel is the bootloader, no GRUB
- **Display:** Wayland via dwl compositor (dwm-like)
- **Audio:** PipeWire (started as user service)
- **Networking:** dhcpcd (ethernet only)
- **Package manager:** dpack (custom, written in Rust)
- **Shell:** zsh (user) / bash (build scripts)
- **Filesystem:** ext4

## Project Structure

```
darkforge/
├── CLAUDE.md              # Project directive (AI assistant context)
├── README.md              # This file
├── docs/
│   └── CHANGELOG.md       # Mandatory changelog for every change
├── src/
│   ├── dpack/             # Custom package manager (Rust)
│   ├── iso/               # Live ISO builder
│   ├── install/           # Interactive installer
│   └── repos/             # Package definitions (124 packages)
│       ├── core/          # 67 base system packages
│       ├── extra/         # 26 libraries and frameworks
│       ├── desktop/       # 19 Wayland/desktop packages
│       └── gaming/        # 12 gaming packages
├── toolchain/             # Cross-compilation bootstrap scripts
│   ├── scripts/           # 34 build scripts (LFS Ch. 5-7)
│   ├── sources/           # Downloaded source tarballs
│   └── VERSION_MANIFEST.md
├── kernel/
│   └── config             # Hardware-specific kernel .config
├── configs/
│   ├── rc.conf            # System configuration
│   ├── inittab            # SysVinit config
│   ├── rc.d/              # Service scripts
│   ├── zprofile           # User shell profile (auto-starts dwl)
│   └── fstab.template     # Filesystem table template
└── reference/             # LFS, BLFS, CRUX, Gentoo reference docs
```

## Build Phases

The project is built in sequential phases. Each phase has clear deliverables and exit criteria.

| Phase | Description | Status |
|-------|-------------|--------|
| 0 | Toolchain bootstrap (cross-compiler) | Scripts written |
| 1 | dpack core (parser, resolver, sandbox, db, build) | Implemented |
| 2 | dpack advanced (converters, solib, upgrade/remove) | Implemented |
| 3 | Base system packages (66 core/ definitions) | Complete |
| 4 | Kernel configuration | Complete |
| 5 | Init system and service scripts | Complete |
| 6 | Desktop environment (Wayland/dwl) | Definitions written |
| 7 | NVIDIA driver stack | Definition written |
| 8 | Gaming stack (Steam, Wine, Proton) | Definitions written |
| 9 | Application stack (WezTerm, FreeCAD) | Definitions written |
| 10 | ISO builder | Script written |
| 11 | Interactive installer | Scripts written |
| 12 | Integration testing | Pending |

## Quick Start

### Prerequisites

Building DarkForge requires a Linux host system. The toolchain bootstrap (Phase 0) can be done from any modern Linux distro, but later phases require the DarkForge chroot/live environment.

**Host system requirements (for building the toolchain):**

Any reasonably modern Linux distribution works. Tested on:
- Arch Linux (recommended — rolling release with fresh packages)
- Ubuntu 22.04+ / Debian 12+
- Fedora 38+

Required host packages:

```bash
# Arch Linux
sudo pacman -S base-devel git wget python rust

# Ubuntu / Debian
sudo apt install build-essential git wget python3 curl bison gawk m4 texinfo

# Fedora
sudo dnf groupinstall "Development Tools" && sudo dnf install git wget python3 rust cargo
```

**Tool versions:**
- GCC 14.1+ or GCC 15.x (for `-march=znver5` support)
- Rust 1.75+ (for building dpack — install via https://rustup.rs)
- Python 3.10+
- GNU Make 4.x+
- ~50GB free disk space for the full build
- ~4GB RAM minimum (16GB+ recommended for parallel builds)

**For kernel building (Phase 4) and later phases:**
These run inside the DarkForge chroot or on the target machine itself. The toolchain built in Phase 0 provides everything needed.

### 1. Build dpack

```bash
cd src/dpack
cargo build --release
sudo install -m755 target/release/dpack /usr/local/bin/
```

### 2. Bootstrap the toolchain

```bash
export LFS=/mnt/darkforge
# Create and mount your target partition, then:
bash toolchain/scripts/000-env-setup.sh
bash toolchain/scripts/000a-download-sources.sh
bash toolchain/scripts/build-all.sh cross
bash toolchain/scripts/build-all.sh temp
# Enter chroot and run Phase 7 scripts
```

### 3. Build the kernel

```bash
cp kernel/config /usr/src/linux-6.19.8/.config
cd /usr/src/linux-6.19.8
make olddefconfig
make -j32
make modules_install
cp arch/x86/boot/bzImage /boot/vmlinuz
```

### 4. Build the ISO

```bash
bash src/iso/build-iso.sh
```

### 5. Install

Boot the ISO on the target machine and run `install`.

## Compiler Flags

All packages are built with Zen 5 optimizations:

```bash
CFLAGS="-march=znver5 -O2 -pipe -fomit-frame-pointer"
CXXFLAGS="${CFLAGS}"
MAKEFLAGS="-j32"
LDFLAGS="-Wl,-O1,--as-needed"
```

## Key Design Decisions

- **No systemd** — SysVinit + rc.d for transparency and speed
- **No bootloader** — EFISTUB direct kernel boot
- **No display manager** — auto-login to tty1, dwl launched from shell profile
- **ext4** — simpler and faster than btrfs for this use case
- **96GB swap** — matches RAM size for hibernation support
- **Single target** — every optimization targets exactly this hardware

## License

The DarkForge project itself is MIT licensed. Individual packages retain their upstream licenses as documented in their `.toml` definitions.

## Repository

```
git@git.dannyhaslund.dk:danny8632/darkforge.git
```