183 lines
6.7 KiB
Markdown
183 lines
6.7 KiB
Markdown
# Phase 16.3: build native FreeBSD base artifacts from materialized source inputs
|
|
|
|
Date: 2026-04-03
|
|
|
|
## Goal
|
|
|
|
Phase 16.3 closes the immediate gap between:
|
|
|
|
- declarative/materialized FreeBSD source inputs, and
|
|
- the native kernel/world/runtime/bootloader build path.
|
|
|
|
Before this step, Fruix could already:
|
|
|
|
- describe FreeBSD sources explicitly, and
|
|
- materialize them into `/frx/store`
|
|
|
|
but native base builds still consumed the ambient host source tree through the package plan's `source-root`.
|
|
|
|
After this step, native FreeBSD base artifacts are driven by the declared source input's **materialized store snapshot** instead.
|
|
|
|
## Implementation
|
|
|
|
### Native package materialization now injects materialized source inputs
|
|
|
|
`modules/fruix/system/freebsd.scm` now prepares native FreeBSD packages differently from copy-based packages.
|
|
|
|
For native packages, Fruix now:
|
|
|
|
1. reconstructs the declared `freebsd-source` from the package plan
|
|
2. materializes that source under Fruix control
|
|
3. rewrites the native build plan to use the materialized source root
|
|
4. records both the declared source and the materialized/effective source in the output metadata
|
|
5. adds the materialized source store path to the package references
|
|
|
|
This means native package output identity now depends on:
|
|
|
|
- the declared source object
|
|
- the resolved/materialized source identity
|
|
- the materialized source root and tree hash
|
|
|
|
rather than on an ambient host tree path.
|
|
|
|
### Native build manifests now record both declared and materialized source identity
|
|
|
|
Native package manifests now include:
|
|
|
|
- `declared-source`
|
|
- `materialized-source`
|
|
- the `native-build-common` block derived from the materialized source root
|
|
|
|
Native `.freebsd-native-build-info.scm` files now record:
|
|
|
|
- declared source
|
|
- materialized source store path
|
|
- materialized source root
|
|
- materialized source tree hash
|
|
- effective source details such as resolved Git commit or verified archive SHA256
|
|
|
|
### Source tree hashing now reuses materialized-source metadata when available
|
|
|
|
The native build common manifest now prefers the materialized source tree hash when one is already known, rather than recomputing it unnecessarily.
|
|
|
|
### Package caching is now manifest-driven rather than name/version-only
|
|
|
|
The in-process package materialization cache for native builds now keys on the computed manifest identity rather than only:
|
|
|
|
- package name
|
|
- package version
|
|
|
|
That is important once multiple source-driven variants of the same native package version can coexist.
|
|
|
|
### System closures now record source materializations explicitly
|
|
|
|
`materialize-operating-system` now keeps a dedicated source-materialization cache while building native packages.
|
|
|
|
Closures now record:
|
|
|
|
- `metadata/freebsd-source-materializations.scm`
|
|
- `materialized-source-store-count`
|
|
- `materialized-source-stores`
|
|
|
|
and system references now include the materialized source stores explicitly.
|
|
|
|
This makes the source artifacts themselves part of the closure provenance boundary.
|
|
|
|
### `fruix system` metadata now exposes materialized source stores
|
|
|
|
`scripts/fruix.scm` now emits for `fruix system build` and `image`:
|
|
|
|
- `freebsd_source_materializations_file`
|
|
- `materialized_source_store_count`
|
|
- `materialized_source_stores`
|
|
|
|
This makes it easy for harnesses and operators to see which source store snapshot was actually used for a build.
|
|
|
|
## New files
|
|
|
|
Added:
|
|
|
|
- `tests/system/phase16-git-materialized-source-operating-system.scm.in`
|
|
- `tests/system/run-phase16-source-driven-native-build.sh`
|
|
- `docs/reports/phase16-source-driven-native-builds-freebsd.md`
|
|
|
|
## Validation
|
|
|
|
Passing runs:
|
|
|
|
- `PASS phase16-source-driven-native-build`
|
|
- `PASS phase16-source-materialization`
|
|
- `PASS phase16-declarative-source-build`
|
|
|
|
### Source-driven native build validation
|
|
|
|
Validated a native system build from a declared Git source:
|
|
|
|
- source kind:
|
|
- `git`
|
|
- source URL:
|
|
- `https://git.FreeBSD.org/src.git`
|
|
- source ref:
|
|
- `stable/15`
|
|
- resolved commit during validation:
|
|
- `332708a606f6bf0841c1d4a74c0d067f5640fe89`
|
|
|
|
The test intentionally declared an **unused transitional source-root**:
|
|
|
|
- `/var/empty/fruix-unused-source-root`
|
|
|
|
and still built successfully, proving the native build path now uses the materialized source snapshot rather than the ambient declared root.
|
|
|
|
Confirmed build metadata:
|
|
|
|
```text
|
|
closure_path=/frx/store/efed0b8ee31b4f3f97b8ae04317ccd2f3f8a88e332172e2bf0bb4295271c6023-fruix-system-fruix-freebsd
|
|
kernel_store=/frx/store/c7e094a450f017a35c2d4d66451dcda893bc4ac27d810295fa491e41fdae8551-freebsd-native-kernel-15.0-STABLE-git-materialized
|
|
bootloader_store=/frx/store/36432acf23cdff7eb7601bd314ea82d75a5e7fbcd3480d753117f4c5f9a7c7db-freebsd-native-bootloader-15.0-STABLE-git-materialized
|
|
runtime_store=/frx/store/b6f9ebb5c844aedc3d4395ad08542eb67965a19fc28f68fb0f4b55f91aef1c8f-freebsd-native-runtime-15.0-STABLE-git-materialized
|
|
materialized_source_store=/frx/store/bcbf7554ce43d40b1bdc98823eb450ce050529b34bbe2dae2a9df48688004c4b-freebsd-source-stable15-network-source
|
|
materialized_source_root=/frx/store/bcbf7554ce43d40b1bdc98823eb450ce050529b34bbe2dae2a9df48688004c4b-freebsd-source-stable15-network-source/tree
|
|
resolved_commit=332708a606f6bf0841c1d4a74c0d067f5640fe89
|
|
source_driven_native_build=ok
|
|
```
|
|
|
|
The harness also verified that:
|
|
|
|
- closure metadata records exactly one materialized source store
|
|
- `metadata/freebsd-source-materializations.scm` exists
|
|
- `metadata/store-layout.scm` records the materialized source store count/path
|
|
- native build info files for kernel, bootloader, and runtime all record:
|
|
- a `declared-source` block with `ref . "stable/15"`
|
|
- a `materialized-source` block
|
|
- the materialized source store path
|
|
- the materialized source root
|
|
- the resolved Git commit
|
|
- native build info files do **not** use the unused declared source root as their actual `source-root`
|
|
|
|
### Regression checks
|
|
|
|
Re-ran:
|
|
|
|
- `PASS phase16-source-materialization`
|
|
- `PASS phase16-declarative-source-build`
|
|
|
|
The local-tree declarative source build now also drives native base outputs from a materialized local source snapshot in `/frx/store`, while preserving the same declared source metadata interface.
|
|
|
|
## Result
|
|
|
|
Phase 16.3 is complete.
|
|
|
|
Fruix native FreeBSD base artifacts are now built from the declared source input's materialized store snapshot rather than directly from ambient `/usr/src`.
|
|
|
|
That means Fruix has crossed the key source boundary planned for Phase 16:
|
|
|
|
- source inputs can be declared
|
|
- source inputs can be fetched/materialized
|
|
- native base artifacts can now consume those materialized source inputs
|
|
|
|
The next logical phase is no longer source modeling itself, but what to do with that stronger source boundary:
|
|
|
|
- side-by-side source revisions
|
|
- boot validation from distinct source revisions
|
|
- and then installation/deployment ergonomics on top of those source-driven native builds
|