Declarative Linux from source — built your way.
LFS • BLFS • CLFS • MLFS • GLFS • SLFS
Quick Start • About • How It Works • Supported Books • Configuration • Post-Build • Contributing
ForgeLFS is a declarative system construction framework that compiles a complete Linux system entirely from source code. It takes the Linux From Scratch (LFS) books — the gold standard for understanding how Linux works — and automates the entire process through a state-driven build engine, a dependency-resolving package manager, and a terminal user interface.
ForgeLFS is not a distribution. It produces your Linux system, built according to your choices, from source code you can audit. It is the build engine, the recipe system, the dependency resolver, the feature flags, the cross-compilation scaffolding, and the TUI dispatch — everything you need to forge a Linux system from raw source.
A GENUINE WARNING. FORGELFS, IN IT'S CURRENT STATE IS UNTESTED.
The LFS books teach you how Linux works by having you type every command. That's invaluable — once. After you've built LFS manually two or three times, you understand the process. What you want next is control without repetition.
ForgeLFS gives you:
- Repeatability — Build the same system twice and get identical results
- Customization — Select packages, toggle feature flags, choose your init system
- Resume — Crash during the 45-SBU GCC build? Resume from where you left off
- Package management — The
anviltool tracks every file so you can remove, verify, and upgrade - Cross-compilation — Build for ARM64 on an x86_64 host
- Offline builds — Fetch all sources once, build anywhere
ForgeLFS is a build framework that implements the LFS books. It is not affiliated with or endorsed by the Linux From Scratch project. The LFS books are the specification; ForgeLFS is an independent automation engine that follows that specification. Users are strongly encouraged to read the LFS book alongside ForgeLFS to understand what is being built and why.
ForgeLFS recommends the Gentoo LiveGUI USB image as the build host. It ships with all required build tools pre-installed and is distribution-agnostic.
# Download from: https://www.gentoo.org/downloads/
# Boot the LiveGUI USB, open a terminal, then:git clone --recursive https://github.com/realvolk/ForgeLFS.git
cd ForgeLFS
chmod +x forge-lfs
sudo ./forge-lfsYou'll be greeted by a TUI where you select your target disk, filesystem, bootloader, kernel configuration, init system, and build profile. Confirm, and ForgeLFS builds your system.
Any Linux system with the tools listed in LFS §2.2 will work. ForgeLFS
automatically checks for required host tools during the preflight stage.
Missing tools will be reported and can be installed with your host's package
manager.
| Situation | Log location |
|---|---|
| Build failure | /tmp/forge-lfs/build.log |
| Toolchain stage | /tmp/forge-lfs/toolchain.log |
| Per-package logs | $LFS/tmp/anvil/build/logs/<pkgname>.log |
Include these in any GitHub issue.
ForgeLFS builds a Linux system in eight stages:
preflight → Host checks, tool verification, network test
storage → Partition disk, create filesystem, mount $LFS
prepare → Directory layout, lfs user, download all sources
toolchain → Cross-compile binutils, gcc, glibc (§5-6)
chroot → Enter chroot, build additional temporary tools (§7)
system → Build the full LFS system via anvil (§8, ~80 packages)
configure → Hostname, locale, network, systemd configuration (§9)
boot → Kernel build, GRUB installation (§10)
Stages 1-4 run on the host system. Stage 5 enters the chroot. Stages 6-8 run inside the new system. Each stage saves a sentinel file — if the build is interrupted, ForgeLFS resumes from the last completed stage.
At the core of ForgeLFS is anvil, a source-based package manager implemented in Bash. Anvil:
- Resolves dependencies using topological sort
- Fetches and verifies source tarballs against MD5 checksums
- Compiles packages with profile-driven compiler flags
- Runs test suites (or skips them, if configured)
- Creates binary artifacts for reuse
- Tracks file inventory for verification and uninstall
- Supports feature flags with conditional dependencies
Anvil is installed to the target system at /usr/local/bin/anvil for post-build package management.
All build decisions are stored in /tmp/forge-lfs/state.conf — a flat key-value file. The TUI writes to it. Every stage reads from it. If the system reboots mid-build, the state file survives on the host's tmpfs and the build can resume.
ForgeLFS is designed to support the entire LFS family:
| Book | Status | Description |
|---|---|---|
| LFS 13.0-systemd | ✅ Complete | Base Linux system with systemd init |
| LFS 13.0-sysv | 🔜 Planned | Base Linux system with SysVinit |
| BLFS 13.0 | 🔜 Planned | Beyond LFS — desktop, server, tools (~500 packages) |
| CLFS | 🔧 Engine ready | Cross-compiled LFS for ARM, RISC-V, etc. |
| MLFS | 🔜 Planned | Multilib — 32-bit support on 64-bit |
| GLFS | 🔜 Planned | Gaming — Steam, Wine, Vulkan, NVIDIA |
| SLFS | 🔜 Planned | Supplemental — Hyprland, Flatpak, emulators |
The engine and recipe format are identical across all books. Adding a new book means adding recipes and a .LIST entry — no engine changes required.
ForgeLFS ships with four compilation profiles:
| Profile | CFLAGS | Features |
|---|---|---|
default |
-march=native -O2 -pipe |
Balanced for daily use |
safe |
-O2 -fstack-protector-strong |
Security-focused |
performance |
-O3 -march=native -flto=auto |
Maximum speed |
hardened |
-O2 -fstack-protector-strong -fPIE |
PIE + RELRO + SSP |
Packages can declare feature flags that pull in optional dependencies. Toggle them with:
anvil flag <pkg> # List flags
anvil flag <pkg> <flag> on|off # Enable or disableForgeLFS supports three kernel configuration methods:
defconfig— Default configuration for your architecturemenuconfig— Interactive ncurses menulocalmodconfig— Build only modules currently loaded on the host
Kernel config fragments can be placed in /etc/anvil/kernel.d/ for automatic application.
After the build completes, ForgeLFS offers:
- Anvil package manager — Installed to
/usr/local/bin/anvilfor ongoing source-based package management - Root filesystem tarball — For deployment to other machines
- Flashable image — For ARM/embedded targets
- Atomic cutover — BTRFS snapshot or kexec-based system activation
The user is responsible for maintaining the system after the build. Anvil provides the tools; the user decides what to install, upgrade, or remove.
anvil list # List installed packages
anvil list-recipes # List available recipes
anvil world status # Show world file status
anvil world add <pkg> # Add package to world file
anvil world build # Build all packages in world
anvil rebuild <pkg> # Rebuild a specific package
anvil remove <pkg> # Uninstall a source-built package
anvil files <pkg> # List files owned by a package
anvil verify <pkg> # Verify installed files exist
anvil gc # Garbage collect unused artifacts
anvil audit # Security audit of built binaries- Not a distribution. It produces a custom Linux system; it does not maintain it with security updates or binary packages.
- Not a hand-holder. The user is expected to read the LFS books alongside the tool. ForgeLFS automates the typing, not the understanding.
- Not a package manager replacement.
anvilmanages source-built packages. It does not replaceapt,dnf, orpacmanfor binary software — though nothing stops you from installing those on your LFS system. - Not dependent on any specific host. It runs on any Linux host that meets LFS §2.2 requirements.
ForgeLFS/
├── forge-lfs # Entry point
├── VERSION
├── README.md
├── DOCUMENTS/ # Specification, changelog, license
├── FILLY/ # TUI widget library (submodule)
├── scripts/
│ ├── common.sh # Shared utilities
│ ├── state.sh # State machine with stage validation
│ ├── tui/
│ │ ├── core.sh # TUI dispatch (msg, yesno, input, menu, hub)
│ │ └── menu.sh # Build configuration hub
│ ├── stages/
│ │ ├── preflight.sh # Host checks, tool verification
│ │ ├── storage.sh # (handled by storage/ directory)
│ │ ├── prepare.sh # Directory layout, lfs user, source download
│ │ ├── toolchain.sh # Cross-compile binutils, gcc, glibc (§5-6)
│ │ ├── chroot.sh # Enter chroot, build temporary tools (§7)
│ │ ├── system.sh # Build full LFS system via anvil (§8)
│ │ ├── configure.sh # Hostname, locale, network, systemd (§9)
│ │ ├── boot.sh # Kernel build, bootloader (§10)
│ │ └── finalize.sh # Release files, unmount, completion
│ ├── storage/
│ │ ├── partition.sh # Disk partitioning (MBR/GPT, LVM, LUKS)
│ │ ├── filesystem.sh # Filesystem creation (ext4/btrfs/xfs/f2fs)
│ │ └── mount.sh # Mount with BTRFS subvolume support
│ └── install/
│ ├── bootloader.sh # Bootloader dispatch with root cmdline generation
│ ├── bootloaders/
│ │ ├── grub.sh # GRUB (BIOS + UEFI, LUKS, LVM)
│ │ ├── limine.sh # Limine bootloader
│ │ ├── refind.sh # rEFInd (stub)
│ │ └── efistub.sh # EFIStub (stub)
│ └── users.sh # Root/user password and account creation
├── forge/ # Build engine (anvil)
│ ├── bin/
│ │ ├── anvil # Package manager entry point
│ │ ├── anvil_cli.bash # CLI commands (fetch, rebuild, world, flag)
│ │ ├── anvil_common.bash # Shared utilities and FILLY integration
│ │ └── anvil_tui.bash # TUI hub for anvil
│ ├── lib/
│ │ ├── builder.bash # build_package(), fetch_sources(), fetch() hook
│ │ ├── recipe.bash # load_recipe(), feature flag parsing
│ │ ├── deps.bash # Topological dependency resolution
│ │ ├── flags.bash # Feature flag system with conflict detection
│ │ ├── validate.bash # Recipe validation
│ │ ├── cache.bash # Build artifact caching
│ │ ├── queue.bash # Build queue with parallel support
│ │ ├── rebuild.bash # Rebuild detection (flags changed, deps updated)
│ │ ├── heal.bash # Auto-heal recipes on build failure
│ │ ├── hwdetect.bash # Hardware detection for kernel config
│ │ └── kconfig_fragments.bash # Kernel config fragment application
│ ├── tui/
│ │ ├── menu.sh # Forge build configuration hub
│ │ └── progress.sh # Build timing summary
│ ├── profile/
│ │ ├── default.sh # -march=native -O2 -pipe
│ │ ├── safe.sh # Security-focused flags
│ │ └── hardened.sh # PIE + RELRO + SSP
│ ├── world/
│ │ └── lfs-13.0-systemd.world # LFS Chapter 8 package list
│ ├── kernel.d/ # Kernel config fragments
│ └── db/ # Package database
└── presets/ # Saved build configurations
- FILLY — Pure C widget library, bundled as a submodule. Builds with
gccandmake. Installed to/usr/local/bin/filly. Handles all TUI rendering and input. No external runtime dependencies.
Everything else is either part of the LFS host requirements or built during the bootstrap process.
ForgeLFS is under active development. Contributions are welcome and appreciated.
Looking for: Testers • Recipe writers • ARM/embedded testers • FILLY plugin developers
Please read the Contributing Guidelines before submitting pull requests.
Recipes live in the ForgeLFS-recipes repository. See that repository's README for the recipe format and submission guidelines.
- ArtixForge — The progenitor. ForgeLFS is ArtixForge with all distribution-specific logic removed, leaving the build engine, recipe system, and TUI framework.
- GForge — Another ArtixForge fork, targeting Gentoo Linux.
- Forge Recovery Suite (FRS) — Extracted from ArtixForge's recovery subsystem. ForgeLFS and FRS share the same parent codebase and the same state machine architecture.
- Volk Forge Framework (VFF) — The architectural pattern shared by ArtixForge, GForge, ForgeLFS, and FRS. ArtixForge is the progenitor that established the pattern; ForgeLFS is the most complete extraction of the pure build framework.
- jhalfs (ALFS) — The official LFS automation tool. jhalfs parses the LFS XML book and generates Makefiles. ForgeLFS takes a different approach: recipes are first-class build definitions, the dependency resolver determines build order, and the state machine handles resume and recovery.
Licensed under the Forge Attribution License 1.0
© Volk 2026
Build your system. Your rules. Your source.