fruix/docs/reports/phase20-development-environment-freebsd.md

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:

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:

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