# Phase 20.1: Fruix-managed development environment for native FreeBSD base work

Date: 2026-04-05

## Goal

Validate that a booted Fruix-managed FreeBSD system can expose a usable development environment for deeper native base work without collapsing the runtime/development boundary back into one broad profile.

This step explicitly builds on the Phase 14 split between:

- native runtime/boot artifacts for the running system
- separate development-facing artifacts such as headers and toolchain pieces

The goal is **not** full self-hosting yet.

It is to prove that a running Fruix system can expose the tools and paths needed for native FreeBSD build work in a controlled way.

## Implementation

### New operating-system field

`modules/fruix/system/freebsd/model.scm` now supports:

- `#:development-packages`
- `operating-system-development-packages`

The default remains empty, so existing systems do not change unless they opt in.

### Separate development profile inside the system closure

`modules/fruix/system/freebsd/media.scm` now materializes an additional profile tree when `development-packages` is non-empty:

- `/frx/store/...-fruix-system-.../development-profile`

The main runtime tree remains:

- `/frx/store/...-fruix-system-.../profile`

This preserves the runtime/development split:

- runtime stays under `profile`
- development tooling stays under `development-profile`

The development stores are also now part of the closure references and recorded in `metadata/store-layout.scm`.

### In-guest development environment helper

Opt-in systems with development packages now ship:

- `/usr/local/bin/fruix-development-environment`

and expose a stable runtime link:

- `/run/current-development -> /run/current-system/development-profile`

The helper emits shell exports for the active development profile, including at least:

- `FRUIX_DEVELOPMENT_PROFILE`
- `FRUIX_DEVELOPMENT_INCLUDE`
- `FRUIX_DEVELOPMENT_SHARE_MK`
- `FRUIX_CC`
- `FRUIX_CXX`
- `FRUIX_AR`
- `FRUIX_RANLIB`
- `FRUIX_NM`
- `FRUIX_BMAKE`
- `CPPFLAGS`
- `MAKEFLAGS`
- `PATH`

Intended use:

```sh
eval "$(/usr/local/bin/fruix-development-environment)"
```

### Chosen development overlay for this phase

For the validated Phase 20.1 guest path, the development overlay is intentionally narrow:

- `freebsd-native-headers`
- `freebsd-clang-toolchain`

This was chosen deliberately.

The earlier standalone Phase 14 development-profile package set was designed for broad profile composition, but for a running Fruix system it unnecessarily duplicated runtime pieces already present in the system profile.

For native base work, the important additions here are:

- `usr/include`
- `usr/share/mk`
- Clang/binutils-style frontend tools

while the running system already supplies:

- base runtime
- `/usr/bin/make`
- system libraries and boot/runtime state

That keeps the Phase 20.1 environment focused on native base development rather than reintroducing a broad mixed profile.

## New files

Added:

- `tests/system/phase20-development-operating-system.scm.in`
- `tests/system/run-phase20-development-environment-xcpng.sh`

## Validation

Passing run:

- `PASS phase20-development-environment-xcpng`
- workdir: `/tmp/fruix-phase20-development-xcpng`

Validated on the approved real XCP-ng path:

- VM `90490f2e-e8fc-4b7a-388e-5c26f0157289`
- VDI `0f1f90d3-48ca-4fa2-91d8-fc6339b95743`

Representative result:

```text
closure_path=/frx/store/c0ad43d7ef72323d4270a4f1e96ca1f5cc99566c-fruix-system-fruix-freebsd
development_profile_path=/frx/store/c0ad43d7ef72323d4270a4f1e96ca1f5cc99566c-fruix-system-fruix-freebsd/development-profile
development_profile_guest=/run/current-system/development-profile
cc_version=FreeBSD clang version 19.1.7 (https://github.com/llvm/llvm-project.git llvmorg-19.1.7-0-gcd708029e0b2)
hello_direct=hello-from-direct-dev-env
hello_make=hello-from-make-dev-env
development_environment=ok
```

The harness verified all of the following on the real booted Fruix guest:

- runtime boot/regression still succeeds on XCP-ng
- the closure contains a separate `development-profile`
- runtime `profile` does **not** regain headers or `usr/share/mk`
- `/usr/local/bin/fruix-development-environment` exists and emits the expected exports
- `/run/current-development` points at `/run/current-system/development-profile`
- direct compilation works with the exported Clang toolchain and headers
- a simple native FreeBSD `make` build using `.include <bsd.prog.mk>` also succeeds

## Result

Phase 20.1 is complete.

Fruix now validates a real booted FreeBSD system path where:

- the running system remains lean and runtime-focused
- native development artifacts are exposed separately and explicitly
- the guest can compile code directly with the Fruix-provided toolchain
- the guest can also drive a simple `bsd.prog.mk` build using the exported development environment

This is enough to say that Fruix can host a controlled native FreeBSD base-development environment, without yet claiming full self-hosting.

## Next step

Per `docs/PLAN_4.md`, the next planned step is:

- **Phase 20.2** — run host-initiated native base builds inside a Fruix-managed environment