fruix/docs/reports/phase1-guix-build-gap-analysis.md

# Phase 1.2 follow-up: gap analysis between current FreeBSD prototypes and a real Guix package build

Date: 2026-04-01

## Summary

This step documents the concrete remaining gap between the current FreeBSD validation harnesses and a true Guix package/derivation/store-daemon build.

The repository now has three relevant validation layers:

- native shell-driven GNU Hello build:
  - `tests/native-build/run-gnu-hello.sh`
- Scheme-driven GNU Hello builder-phase prototype:
  - `tests/native-build/gnu-hello-guix-phase-runner.scm`
  - `tests/native-build/run-gnu-hello-guix-phase-runner.sh`
- Scheme-driven GNU which builder-phase prototype:
  - `tests/native-build/gnu-which-guix-phase-runner.scm`
  - `tests/native-build/run-gnu-which-guix-phase-runner.sh`

Those prototypes prove that FreeBSD can already execute a small but real subset of Guix builder-side GNU build logic when paired with the fixed local Guile build.

They do **not** yet prove that FreeBSD can perform an actual Guix package build.

## Current validated surface

What is already validated on FreeBSD amd64:

1. Guile can run the necessary Scheme code, provided the locally fixed Guile build is used.
2. Guix builder-side `(guix build gnu-build-system)` code can run a subset of `%standard-phases`.
3. Two small GNU packages build successfully through that subset:
   - GNU Hello
   - GNU which
4. The following builder phases have been exercised successfully:
   - `set-SOURCE-DATE-EPOCH`
   - `unpack`
   - `configure`
   - `build`
   - `check`
   - `install`

This means the question is no longer "can FreeBSD run any Guix builder-side GNU phase logic at all?"

The question is now "what still separates these prototypes from a real Guix package build?"

## What a real Guix package build does beyond the current prototypes

At a high level, a real Guix package build goes through these layers:

1. package object -> bag lowering
   - `package->bag` in `~/repos/guix/guix/packages.scm`
2. bag -> derivation lowering
   - `bag->derivation` in `~/repos/guix/guix/packages.scm`
3. build-system lowering and builder gexp creation
   - `lower` and `gnu-build` in `~/repos/guix/guix/build-system/gnu.scm`
4. gexp residualization into store items and imported module closures
   - `lower-object` in `~/repos/guix/guix/gexp.scm`
5. daemon connection and build request submission
   - `open-connection` and `set-build-options` in `~/repos/guix/guix/store.scm`
   - `build-derivations` in `~/repos/guix/guix/derivations.scm`
6. daemon-side execution with store management, build users, and isolation
   - `guix-daemon` behavior documented in `~/repos/guix/doc/guix.texi`
   - daemon implementation details in `~/repos/guix/nix/libstore/build.cc`

The current FreeBSD prototypes only validate a slice of step 3, and they do so in a manually constructed environment.

## Gap matrix

### 1. Package lowering is not exercised yet

Current prototypes:

- call `gnu-build` directly
- manually provide the source tarball URL/hash context
- manually choose outputs and phases

Missing real Guix behavior:

- no `<package>` object is lowered through `package->bag`
- no implicit inputs are attached by `lower`
- no `package->derivation` call occurs
- no real `.drv` file is generated

Why this matters:

A large amount of actual Guix behavior lives above the builder-phase layer. The package record, arguments, native inputs, propagated inputs, outputs, search paths, and implicit inputs are all resolved before the builder runs.

FreeBSD implication:

The current prototypes show that builder-side Scheme logic works, but they do not yet show that Guix's host-side package lowering logic can successfully target FreeBSD.

### 2. Implicit GNU build-system inputs are bypassed

In real Guix, `gnu-build-system` adds implicit inputs through `standard-packages` in `~/repos/guix/guix/build-system/gnu.scm`, which ultimately comes from `%final-inputs` in `~/repos/guix/gnu/packages/commencement.scm`.

That implicit input set includes toolchain and utility packages such as:

- `tar`
- `gzip`
- `bzip2`
- `file`
- `diffutils`
- `patch`
- `findutils`
- `gawk`
- `zstd`
- `sed`
- `grep`
- `xz`
- `coreutils`
- `make`
- `bash`
- `ld-wrapper`
- `binutils`
- `gcc`
- `libc`
- `libc:static`

Current prototypes instead rely on host tools already present on FreeBSD, such as:

- `fetch`
- `sha256`
- `bsdtar`
- `/bin/sh`
- `/usr/bin/install`
- host `cc`
- host `make`

Why this matters:

A real Guix package build is not just "run the phases somehow". It runs them with a specific Guix-managed tool universe and search-path model.

FreeBSD implication:

The current prototypes do not yet answer whether Guix's implicit input model can be lowered, realized, and used coherently on FreeBSD.

### 3. Imported module closure and build-side module materialization are bypassed

Real `gnu-build` in `~/repos/guix/guix/build-system/gnu.scm` builds a gexp that uses `with-imported-modules` and `gexp->derivation` so that builder-side modules become store material.

Current prototypes instead:

- set `GUILE_LOAD_PATH` directly to `~/repos/guix`
- load Guix modules straight from the checkout
- do not build/store an imported module closure
- do not validate generated Guix configuration modules such as `guix config`

Why this matters:

This is one of the biggest remaining gaps. Our prototypes prove that the builder-side code itself can run, but they do not prove that Guix can correctly package up the builder program, its modules, and its imported dependencies as a derivation input graph.

FreeBSD implication:

Before a true Guix package build can work, FreeBSD will need a functioning path for:

- imported Guix Scheme modules
- build-side module resolution in a store context
- derivation generation for those module closures

### 4. The store is still only simulated

Current prototypes use store-like output names under `/tmp`, for example:

- `/tmp/.../0000000000000000-hello-2.12.3`
- `/tmp/.../0000000000000000-which-2.21`

Missing real Guix behavior:

- no canonical `/gnu/store`
- no true content-addressed store path computation
- no `.drv` path registration
- no store database updates
- no garbage-collection roots
- no validity registration or reference graph maintenance

Why this matters:

Guix's reproducibility, dependency tracking, and garbage collection all depend on the real store, not just on an output directory that looks store-like.

FreeBSD implication:

A real FreeBSD port must eventually establish a functioning `/gnu/store` equivalent with daemon-managed metadata, not just staged output directories.

### 5. No daemon RPC path has been validated

Real Guix clients talk to the daemon using `open-connection` in `~/repos/guix/guix/store.scm` and submit builds through `build-derivations` in `~/repos/guix/guix/derivations.scm`.

Current prototypes:

- do not connect to a daemon
- do not negotiate the daemon protocol
- do not set build options via `set-build-options`
- do not submit derivations for building

Why this matters:

Even if derivation generation were to succeed on FreeBSD, Guix still needs an operational daemon path to realize builds and manage the store.

FreeBSD implication:

At some point the port must stop being "Scheme code can run locally" and become "a Guix client can ask a daemon to build something".

### 6. No real build isolation or build-user model is in place

The Guix manual section on `guix-daemon` documents that builds normally run:

- under dedicated build users from `--build-users-group`
- in a chroot containing only declared dependencies
- and on GNU/Linux, inside additional namespaces/containers

The daemon code in `~/repos/guix/nix/libstore/build.cc` also clearly depends on:

- a build-users group
- UID switching
- temporary build directories
- chroot setup
- Linux container features when available

Current prototypes:

- run as the current user
- do not switch to build users
- do not restrict filesystem visibility to declared inputs
- do not use chroot
- do not use jails
- do not isolate network access

Why this matters:

This is the largest architectural gap relative to the final FreeBSD goal.

FreeBSD implication:

The current results are strong evidence for builder-side portability, but they say almost nothing yet about the eventual jail/build-user/isolation design required for a proper port.

### 7. Substitutes, grafts, and offloading are untouched

Real Guix package builds may involve:

- substitutes
- grafts
- daemon-side build options
- offloading

Relevant code paths appear in:

- `package->derivation` in `~/repos/guix/guix/packages.scm`
- `set-build-options` in `~/repos/guix/guix/store.scm`
- `guix-daemon` documentation in `~/repos/guix/doc/guix.texi`

Current prototypes:

- always build locally
- do not use substitutes
- do not test graft behavior
- do not exercise offload logic

Why this matters:

These are not the first blockers for a minimal FreeBSD prototype, but they remain part of the full Guix execution model.

## Practical conclusion

The current FreeBSD work has successfully de-risked the following narrow question:

> Can FreeBSD run Guix builder-side GNU build phases for small packages when Guile is fixed?

Answer: yes.

The next blockers are now clearly above that layer:

1. package lowering to bags/derivations
2. imported module/store materialization
3. real store and daemon connectivity
4. daemon-side isolation and build-user execution

## Most actionable next milestone

The smallest high-value milestone after this analysis is likely:

### Minimal milestone: derivation-generation validation without claiming full build support

Try to validate that FreeBSD can at least get through the host-side lowering path for a tiny package far enough to produce a derivation or identify the first concrete failure point.

That would answer a much sharper question than the current prototypes:

> Does FreeBSD fail first in host-side Guix lowering, in store interaction, or in daemon execution?

This is the narrowest next step that meaningfully approaches a real Guix package build.

## Recommended next step

Proceed with a targeted derivation-generation investigation for a tiny package, using the current GNU Hello package as the first candidate if practical, and record the exact first failure boundary among:

- missing generated Guix modules/configuration
- store connection assumptions
- derivation emission
- daemon availability
- daemon-side execution assumptions