# Phase 5.1: Unblocked the checkout command path on FreeBSD and established a first `fruix` frontend boundary

Date: 2026-04-01

## Summary

This step moves the FreeBSD port from “the checkout configures and builds generated scripts” to “the checkout actually runs useful commands”.

Added files:

- `tests/guix/patches/phase5-checkout-runtime.patch`
- `tests/guix/patches/phase5-guix-daemon-freebsd.patch`
- `tests/guix/setup-phase5-checkout.sh`
- `tests/guix/run-phase5-checkout-runtime.sh`

## Root cause of the `leave-on-EPIPE` failure

The earlier failure:

- `./pre-inst-env guix --version`
- `Wrong type to apply: #<syntax-transformer leave-on-EPIPE>`

was traced to the ordering of top-level definitions in `guix/ui.scm`.

More specifically:

- `show-version-and-exit` called `leave-on-EPIPE`
- `leave-on-EPIPE` was defined later in the file as a syntax transformer
- on this FreeBSD path, the earlier call site was compiled as a value application rather than as a macro expansion site
- when invoked at runtime, Guile attempted to apply the syntax transformer as a procedure

This produced the observed error:

- `Wrong type to apply: #<syntax-transformer leave-on-EPIPE>`

## Runtime patch strategy

The runtime patch takes a deliberately small approach:

1. make `(guix ui)` explicitly non-declarative for this command-path use case
2. rewrite `show-version-and-exit` to use a direct `catch 'system-error` block instead of relying on the later syntax binding
3. parameterize `program-name` in `guix-main`
4. derive the version-banner command name from `program-name`
5. make `(guix scripts repl)` explicitly non-declarative as well, since it also uses `load`

This resolves the FreeBSD checkout runtime failure without forcing a broad internal rename.

## FreeBSD/Fruix frontend policy implemented

The step also establishes the first user-facing `fruix` checkout boundary.

Current policy implemented by the harness:

- retain upstream-derived internal `guix` module and script structure
- generate a `scripts/fruix` symlink next to `scripts/guix`
- rely on the new `program-name` handling so:
  - `./pre-inst-env guix --version` reports `guix ...`
  - `./pre-inst-env fruix --version` reports `fruix ...`

This is intentionally a **front-end boundary**, not a whole-tree rename.

## Validation command

Run command:

```sh
METADATA_OUT=/tmp/phase5-runtime-metadata.txt \
./tests/guix/run-phase5-checkout-runtime.sh
```

## Observed results

The runtime harness validated all of the following successfully:

1. `./pre-inst-env guix --version`
2. `./pre-inst-env guix repl --help`
3. `./pre-inst-env guix build --help`
4. `./pre-inst-env fruix --version`

Observed metadata included:

- `first_guix_version_line=guix (GNU Guix) ...`
- `first_fruix_version_line=fruix (GNU Guix) ...`
- `repl_usage_line=Usage: guix repl [OPTIONS...] [-- FILE ARGS...]`
- `build_usage_line=Usage: guix build [OPTION]... PACKAGE-OR-DERIVATION...`

## Important notes

- the first-step `fruix` boundary currently changes the top-level version banner correctly
- subcommand help output still exposes upstream-derived `guix` wording internally
- this is acceptable for the current transition stage and matches the agreed naming policy:
  - Fruix at the user-facing boundary
  - stable upstream-derived internals unless there is strong reason to rename them

## Conclusion

Phase 5.1 is satisfied on the current FreeBSD prototype track:

- the checkout command path now runs on FreeBSD
- the `leave-on-EPIPE` blocker is resolved in the checkout patch queue
- at least one additional non-trivial checkout subcommand works
- a first user-facing `fruix` checkout frontend boundary now exists without a destabilizing blanket rename