diff --git a/Justfile b/Justfile index f2dc1b23..3beb0e63 100644 --- a/Justfile +++ b/Justfile @@ -84,9 +84,36 @@ build: # Build the OS DDI payload filesystem image (implicit dep of build-installer; # useful when you need the standalone artifact for release publishing). +# +# os-base selects the payload base for the FSDK-vs-Flatcar parity harness +# (projectbluefin/server#129): +# fsdk FSDK-composed payload, the shipped base (default). +# flatcar-reference Imported Flatcar reference tree, the known-good control. +# Routes to bluefin-server-ddi-flatcar-reference.bst, added +# alongside the #126 imported Flatcar reference tree. [group('installer')] -build-ddi: - just bst build oci/bluefin-server-ddi.bst +build-ddi $OS_BASE="fsdk": + #!/usr/bin/env bash + set -euo pipefail + case "$OS_BASE" in + fsdk) + DDI_ELEMENT="oci/bluefin-server-ddi.bst" + ;; + flatcar-reference) + if [ ! -f "elements/oci/bluefin-server-ddi-flatcar-reference.bst" ]; then + echo "ERROR: os-base=flatcar-reference requires the imported Flatcar reference tree" >&2 + echo " (projectbluefin/server#126); element oci/bluefin-server-ddi-flatcar-reference.bst" >&2 + echo " does not exist yet. Add it alongside the #126 tree, then re-run." >&2 + exit 1 + fi + DDI_ELEMENT="oci/bluefin-server-ddi-flatcar-reference.bst" + ;; + *) + echo "ERROR: unknown os-base '${OS_BASE}' (expected 'fsdk' or 'flatcar-reference')" >&2 + exit 1 + ;; + esac + just bst build "${DDI_ELEMENT}" # Export the OS DDI payload + SHA256SUMS to dist/ddi/. [group('installer')] diff --git a/docs/skills/ddi-installer-build.md b/docs/skills/ddi-installer-build.md index 0916d10f..468fa7a1 100644 --- a/docs/skills/ddi-installer-build.md +++ b/docs/skills/ddi-installer-build.md @@ -24,7 +24,7 @@ just cluster-build # submit an Argo workflow to build/publish just build-installer # build the installer locally just export-installer # export installer + UKI + SHA256SUMS to dist/ just export-pxe # export standalone PXE vmlinuz/initrd to dist/ -just build-ddi # build the OS DDI payload +just build-ddi # build the OS DDI payload (see "Payload base" below) just export-ddi # export DDI + SHA256SUMS to dist/ddi/ just build-sysext # build the k0s sysext just export-sysext # export sysext artifacts to dist/sysext/ @@ -34,6 +34,28 @@ just test-installer-artifact # test already-exported artifacts in QEMU without r just tags # show FSDK-derived version tags ``` +### Payload base + +`build-ddi` takes an optional `os-base` argument selecting which payload it +composes. It backs the FSDK-vs-Flatcar parity harness +(projectbluefin/server#129), where the two bases are built and compared: + +```bash +just build-ddi # os-base=fsdk (default) +just build-ddi fsdk # FSDK-composed payload -- the shipped base +just build-ddi flatcar-reference # imported Flatcar reference tree -- the control +``` + +`flatcar-reference` routes to `oci/bluefin-server-ddi-flatcar-reference.bst`. +That element arrives with the imported Flatcar reference tree +(projectbluefin/server#126); until it does, `build-ddi flatcar-reference` +refuses with a message naming #126 rather than building anything. Anything +other than these two values is rejected. + +`export-ddi` always exports the default `fsdk` payload -- it does not forward +`os-base`, so the reference tree is a comparison input, never a release +artifact. + ## Mandatory build path: ghost cluster This project MUST always build on the ghost cluster using distributed BuildStream: @@ -58,7 +80,8 @@ projects: push: true ``` -Then run `just build-installer` or `just build-ddi`. +Then run `just build-installer` or `just build-ddi` (add `flatcar-reference` to +build the parity-harness control instead of the shipped payload). ## Flashing the installer media diff --git a/tests/unit/build_ddi_os_base_test.bats b/tests/unit/build_ddi_os_base_test.bats new file mode 100644 index 00000000..8b8dc84b --- /dev/null +++ b/tests/unit/build_ddi_os_base_test.bats @@ -0,0 +1,176 @@ +#!/usr/bin/env bats +# +# Unit tests for the `os-base` option in the `build-ddi` recipe of the +# top-level Justfile (projectbluefin/server#129). +# +# `build-ddi` composes the shipped Bluefin Server OS payload. The `os-base` +# option selects the payload base for the FSDK-vs-Flatcar parity harness: +# `fsdk` (default) builds the FSDK-composed payload, and `flatcar-reference` +# builds the imported Flatcar reference tree once the #126 element lands. +# +# The recipe never builds a real payload in the test. It delegates to the +# `bst` recipe, which runs `podman`. `podman` is replaced by a logging stub on +# PATH that records its arguments and exits 0, so the recipe that routes +# `os-base` to the right element runs to completion and the chosen element is +# recorded in the call log instead of being composed. + +setup() { + if ! command -v just >/dev/null 2>&1; then + skip "just is not installed" + fi + + REPO_ROOT="$(cd "${BATS_TEST_DIRNAME}/../.." && pwd)" + JUSTFILE="${REPO_ROOT}/Justfile" + SANDBOX="${BATS_TEST_TMPDIR}/sandbox" + BIN_DIR="${BATS_TEST_TMPDIR}/bin" + ELEMENTS="${SANDBOX}/elements" + OCI="${SANDBOX}/oci" + LOG="${BATS_TEST_TMPDIR}/podman.log" + REF_ELEMENT="oci/bluefin-server-ddi-flatcar-reference.bst" + + mkdir -p "$BIN_DIR" "$ELEMENTS" "$OCI" + : > "$LOG" + + # The Justfile's top-level backtick assignments inspect + # elements/freedesktop-sdk.bst. Copy it so loading the sandbox Justfile + # behaves exactly like the real one. + cp "${REPO_ROOT}/elements/freedesktop-sdk.bst" "${ELEMENTS}/" + + make_stub podman 0 +} + +# make_stub +make_stub() { + cat > "${BIN_DIR}/$1" <> "${LOG}" +exit $2 +EOF + chmod +x "${BIN_DIR}/$1" +} + +# run_build [os-base] -- invoke `just build-ddi` with the given base. +run_build() { + local base="${1:-}" + if [ -n "${base}" ]; then + run env PATH="${BIN_DIR}:${PATH}" \ + just --justfile "${JUSTFILE}" \ + --working-directory "${REPO_ROOT}" \ + build-ddi "${base}" + else + run env PATH="${BIN_DIR}:${PATH}" \ + just --justfile "${JUSTFILE}" \ + --working-directory "${REPO_ROOT}" \ + build-ddi + fi +} + +# The fsdk element is the shipped base; the flatcar-reference route must never +# select it, and vice versa. +assert_builds() { + local element="$1" + if ! grep -qF "${element}" "${LOG}"; then + echo "expected podman call to build ${element}" >&2 + echo "---- podman log ----" >&2 + cat "${LOG}" >&2 + return 1 + fi +} + +assert_does_not_build() { + local element="$1" + if grep -qF "${element}" "${LOG}"; then + echo "expected podman call NOT to build ${element}" >&2 + cat "${LOG}" >&2 + return 1 + fi +} + +assert_no_build() { + refute_log "bst" +} + +refute_log() { + if grep -qF -- "$1" "${LOG}" 2>/dev/null; then + echo "expected log NOT to contain: $1" >&2 + cat "${LOG}" >&2 + return 1 + fi +} + +# --- guard shape ------------------------------------------------------------ + +@test "build-ddi still declares the OS_BASE parameter defaulting to fsdk" { + grep -qF 'build-ddi $OS_BASE="fsdk"' "${JUSTFILE}" +} + +# `just` substitutes {{...}} textually into the recipe body before bash parses +# it, so `case "{{OS_BASE}}"` makes `just build-ddi '$(cmd)'` run cmd -- on the +# rejection path too, because the error message interpolates it a second time. +# The `$` on the parameter exports it as an environment variable instead, so +# bash only ever sees "$OS_BASE" and never expands the caller's text. +@test "build-ddi never interpolates os-base into the recipe body" { + run awk '/^build-ddi /{f=1} f&&/\{\{OS_BASE\}\}/{print} f&&/^$/{f=0}' "${JUSTFILE}" + [ -z "${output}" ] +} + +@test "build-ddi still validates os-base against fsdk and flatcar-reference" { + grep -qF "expected 'fsdk' or 'flatcar-reference'" "${JUSTFILE}" +} + +@test "build-ddi still guards the flatcar-reference element's existence" { + grep -qF "os-base=flatcar-reference requires the imported Flatcar reference tree" "${JUSTFILE}" +} + +# --- routing ---------------------------------------------------------------- + +@test "build-ddi with no argument builds the fsdk payload" { + run_build + [ "$status" -eq 0 ] + assert_builds "oci/bluefin-server-ddi.bst" + assert_does_not_build "${REF_ELEMENT}" +} + +@test "build-ddi os-base=fsdk builds the fsdk payload" { + run_build "fsdk" + [ "$status" -eq 0 ] + assert_builds "oci/bluefin-server-ddi.bst" + assert_does_not_build "${REF_ELEMENT}" +} + +@test "build-ddi os-base=flatcar-reference refuses before the element exists" { + # The guard must resolve the element against the project's element-path + # (project.conf: element-path: elements), so a stray copy at a bare + # oci/ path must not satisfy it. Run against a sandbox that has the + # decoy but not elements/oci/, so this stays a refusal test after the + # #126 element lands in the repo. + touch "${OCI}/bluefin-server-ddi-flatcar-reference.bst" + run env PATH="${BIN_DIR}:${PATH}" \ + just --justfile "${JUSTFILE}" \ + --working-directory "${SANDBOX}" \ + build-ddi flatcar-reference + [ "$status" -ne 0 ] + [[ "$output" == *"projectbluefin/server#126"* ]] + assert_no_build +} + +@test "build-ddi rejects an unknown os-base" { + run_build "not-a-base" + [ "$status" -ne 0 ] + [[ "$output" == *"unknown os-base"* ]] + assert_no_build +} + +@test "build-ddi does not execute command substitution in os-base" { + # The marker proves execution rather than mere appearance: the payload's + # own text necessarily shows up in the rejection message, so a string + # assertion could not tell "echoed" from "ran". + local marker="${BATS_TEST_TMPDIR}/injected" + run_build "\$(touch ${marker})" + [ "$status" -ne 0 ] + [ ! -e "${marker}" ] + # The payload is reported verbatim instead. Before the `$OS_BASE` export + # the substitution ran here too, so the name was empty in this message. + [[ "$output" == *"touch ${marker}"* ]] + assert_no_build +}