fruix/docs/reports/phase1-guix-gnu-hello-phase-runner.md

Phase 1.2 follow-up: Scheme-driven GNU Hello build with Guix builder phases on FreeBSD

Date: 2026-04-01

Summary

This step extends the earlier native GNU Hello shell harness by validating a tiny Scheme-driven prototype that uses Guix's actual builder-side GNU build machinery on FreeBSD.

Added files:

• tests/native-build/gnu-hello-guix-phase-runner.scm
• tests/native-build/run-gnu-hello-guix-phase-runner.sh

The prototype does not yet build a real Guix package or derivation, but it does execute a subset of Guix's builder-side %standard-phases from (guix build gnu-build-system) against GNU Hello on FreeBSD.

Why this step matters

The previous Phase 1.2 step showed that FreeBSD can perform a shell-driven native autotools build of GNU Hello.

This step moves closer to actual Guix execution by validating that FreeBSD can run Guix's Scheme-side builder logic when using a fixed local Guile build.

That is important because the earlier packaged FreeBSD guile3 binary still crashes in subprocess helpers such as system*, spawn, and open-pipe*. A Scheme-driven build harness therefore needs the locally fixed Guile path validated in Phase 1.1.

Harness design

The shell wrapper:

• requires a fixed local Guile build
• automatically prepends the matching sibling lib directory to LD_LIBRARY_PATH
• exposes the Guix source tree through GUILE_LOAD_PATH
• creates and cleans up a temporary work directory unless KEEP_WORKDIR=1

The Scheme runner:

1. fetches GNU Hello 2.12.3
2. translates the Guix nix-base32 hash to hexadecimal using (guix base32)
3. verifies the downloaded tarball with sha256(1)
4. invokes gnu-build from (guix build gnu-build-system)
5. runs this phase subset from %standard-phases:
   • set-SOURCE-DATE-EPOCH
   • unpack
   • configure
   • build
   • check
   • install
6. executes the installed hello binary
7. records metadata including test results and runtime dependencies

Unlike the earlier shell harness, this prototype installs directly into a store-like output directory under the temporary work tree, which is closer to actual Guix build behavior.

Source identity

As in the previous step, this uses the GNU Hello source currently referenced by ~/repos/guix/gnu/packages/base.scm:

• version: 2.12.3
• Guix nix-base32: 183a6rxnhixiyykd7qis0y9g9cfqhpkk872a245y3zl28can0pqd
• verified SHA256: 0d5f60154382fee10b114a1c34e785d8b1f492073ae2d3a6f7b147687b366aa0

Verification command

METADATA_OUT=/tmp/gnu-hello-guix-metadata.txt \
  ./tests/native-build/run-gnu-hello-guix-phase-runner.sh

The wrapper used the previously validated local fixed Guile build:

/tmp/guile-freebsd-validate-install/bin/guile

Result

The Scheme-driven build succeeded on FreeBSD 15.0-STABLE amd64.

Observed outcomes:

• source fetch: success
• source hash verification: success
• Guix builder phase execution: success
• configure: success
• build: success
• check: success
• install: success
• runtime execution: success

Observed program output:

Hello, world!

Observed test summary:

# TOTAL: 7
# PASS:  7
# SKIP:  0
# XFAIL: 0
# FAIL:  0
# XPASS: 0
# ERROR: 0

Notable findings

1. Guix builder-side GNU phases can run on FreeBSD

This is the first repository step that successfully exercised actual Guix builder-side GNU build logic on FreeBSD rather than only a shell approximation.

The harness successfully called gnu-build from (guix build gnu-build-system) with a selected subset of %standard-phases.

2. The local fixed Guile build remains necessary for Scheme-driven build orchestration

This harness depends on subprocess helpers such as open-pipe* and invoke, so it must not use the packaged FreeBSD guile3 binary.

Using the fixed local Guile build from earlier Phase 1.1 validation was sufficient.

3. Store-like installation changes the resulting runtime linkage profile

The installed binary ended up in a store-like output directory:

/tmp/.../0000000000000000-hello-2.12.3/bin/hello

Observed runtime dependencies were:

• libc.so.7
• libsys.so.7

This differs from the earlier /usr/local-prefixed native shell harness, where the staged binary also pulled in libiconv.so.2, libintl.so.8, and libthr.so.3.

This is an important data point: a more Guix-like output layout and build path can produce materially different runtime linkage on FreeBSD.

4. The test suite passes in this mode too

Unlike the previous shell harness, this prototype also ran GNU Hello's make check phase successfully.

That gives a stronger signal that the Guix builder-side phase sequence is usable on FreeBSD for at least a minimal GNU autotools package.

What this step demonstrates

This step demonstrates that FreeBSD can support a small but real fragment of Guix build orchestration in Scheme, provided that Guile itself is built from a fixed revision containing the upstream subprocess crash fix.

In practical terms, the host now has validated evidence for all of the following:

1. native shell-driven GNU Hello build works
2. local fixed Guile can safely drive subprocess-heavy Scheme code on FreeBSD
3. Guix builder-side GNU phases can build, test, install, and run GNU Hello on FreeBSD

Remaining limitations

This is still not a full Guix package build:

• no derivation was created
• no store daemon was involved
• no build isolation/jail integration was used
• no dependency graph resolution was performed by Guix package machinery
• only a subset of %standard-phases was exercised

Recommended next step

Continue Phase 1.2 by broadening coverage in one of two ways:

1. run the same Scheme-driven phase-runner approach against another small GNU/autotools package, or
2. start documenting the exact Linux-vs-FreeBSD gaps that remain between this prototype and a real gnu-build-system build driven by Guix package definitions

Either direction would build directly on the harnesses now present in tests/native-build/.