Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 29 additions & 2 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -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')]
Expand Down
27 changes: 25 additions & 2 deletions docs/skills/ddi-installer-build.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/
Expand All @@ -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:
Expand All @@ -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

Expand Down
176 changes: 176 additions & 0 deletions tests/unit/build_ddi_os_base_test.bats
Original file line number Diff line number Diff line change
@@ -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 <name> <exit-code>
make_stub() {
cat > "${BIN_DIR}/$1" <<EOF
#!/usr/bin/env bash
echo "$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
}
Loading