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
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ checks (`scripts/check-skill-frontmatter.sh`, `scripts/check-skill-index.sh`,
before editing it: sources arrive in as few COPYs as origins allow, small
RUN steps fold into neighbours, and per-image ARGs are declared late because
an ARG is part of the cache key of every layer below it.
- **The kernel cache tag** is a hash of `Containerfile.kernel`'s base image,
- **The kernel cache tag** is a hash of `Containerfile.kernel` (whole file),
`scripts/install-ogc-kernel.sh`, `scripts/install-nvidia.sh`, and
`packages/hummingbird.repo` (`scripts/kernel-cache-tag.sh`). Any edit to
those files — comments included — forces a ~45-minute cache rebuild. That is
Expand Down
4 changes: 2 additions & 2 deletions docs/skills/index.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"generated_at": "2026-09-18",
"generated_at": "2026-09-19",
"schema_version": "1.0",
"skills": [
{
Expand Down Expand Up @@ -88,7 +88,7 @@
],
"description": "The kernel cache image, its content-hash tag, and unpack-or-compile behavior. Use when touching install-ogc-kernel.sh, install-nvidia.sh, Containerfile.kernel, or debugging flavored builds.",
"version": "1.0",
"last_updated": "2026-09-05",
"last_updated": "2026-09-19",
"doc_type": "reference"
},
{
Expand Down
2 changes: 1 addition & 1 deletion docs/skills/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
This file is a human-readable mirror of `index.json`. Both are generated by
`scripts/generate_skill_index.py` — do not hand-edit either file.

Generated: 2026-09-18 · schema 1.0 · 8 skills
Generated: 2026-09-19 · schema 1.0 · 8 skills

| id | category | status | one-line purpose |
|---|---|---|---|
Expand Down
18 changes: 14 additions & 4 deletions docs/skills/kernel-cache.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: kernel-cache
version: "1.0"
last_updated: "2026-09-05"
last_updated: "2026-09-19"
id: kernel-cache
one_line_purpose: Understand and rebuild the OGC kernel and NVIDIA module cache image.
entry_point: docs/skills/kernel-cache.md
Expand Down Expand Up @@ -48,21 +48,31 @@ The tag must change whenever anything the cache image contains would change,
and not otherwise, so it is a hash of exactly those inputs (header comment,
`scripts/kernel-cache-tag.sh`):

- The `ARG BASE_IMAGE=` line of `Containerfile.kernel` -- the base image the
cache is built from.
- `Containerfile.kernel`, whole file -- the recipe that builds the cache. Its
`ARG BASE_IMAGE=` line names the base image, but its body is what decides
what the image ends up containing: the repo files copied into the builder,
and the single `RUN` that fills `/cache-out`, and the final stage's
`COPY --from=builder`. Hashing only the `ARG` line would leave an edit to
any of that invisible to the key, and since CI builds the cache image only
when its tag is not already published, the three cached flavors would
silently take an image built from the previous recipe.
- `scripts/install-ogc-kernel.sh` and `scripts/install-nvidia.sh`, whole
files, comments included -- the two scripts that do the building.
- `packages/hummingbird.repo` and `packages/fedora-44.repo` -- the repositories
the toolchain comes from (Fedora 44 is builder-only); a different compiler
produces a different kernel.

Editing either script changes the hash and forces a rebuild, comment-only
Editing any of them changes the hash and forces a rebuild, comment-only
edits included. That is deliberate: the key can only ever rebuild something
that did not need rebuilding, never reuse something stale. A cheaper key
that hashed just the version pins would miss a change to how the kernel is
configured or how the module is linked (header comment,
`scripts/kernel-cache-tag.sh`).

`tests/test_kernel_cache_tag.py` holds the key to that contract: it asserts
that mutating a non-`ARG` line of `Containerfile.kernel`, or any of the four
other hashed files, moves the tag.

The `BASE_IMAGE` in `Containerfile.kernel` must match the one in
`Containerfile`, or the prebuilt NVIDIA module would be linked against a
kernel the image never boots. Two literals, one invariant, so `just check`
Expand Down
18 changes: 13 additions & 5 deletions scripts/kernel-cache-tag.sh
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,27 @@
# The tag under which the kernel cache image is published.
#
# It must change whenever anything the cache image contains would change, and
# not otherwise. Those inputs are the base image it is built from, the two
# scripts that do the building, and the repositories the toolchain comes from --
# a different compiler produces a different kernel -- so the tag is a hash of
# not otherwise. Those inputs are the recipe that builds it, the two scripts
# that do the building, and the repositories the toolchain comes from -- a
# different compiler produces a different kernel -- so the tag is a hash of
# exactly those.
#
# Hashing the whole scripts, comments included, is deliberate: it can only ever
# Containerfile.kernel is hashed whole, not just its ARG BASE_IMAGE= line: its
# body is the recipe. The single RUN decides what lands in /cache-out and the
# final stage decides what is copied out of the builder, so an edit there
# changes the image's contents while leaving the base pin untouched. Since CI
# builds the cache image only when its tag is not already published, a key that
# missed those edits would silently hand the three cached flavors an image
# built from the previous recipe.
#
# Hashing the whole files, comments included, is deliberate: it can only ever
# rebuild something that did not need rebuilding, never reuse something stale.
# A cheaper key that hashed just the version pins would miss a change to how
# the kernel is configured or how the module is linked.
set -euo pipefail
cd "$(dirname "$0")/.."
{
grep -m1 '^ARG BASE_IMAGE=' Containerfile.kernel
cat Containerfile.kernel
cat scripts/install-ogc-kernel.sh scripts/install-nvidia.sh
cat packages/hummingbird.repo packages/fedora-44.repo
} | sha256sum | cut -c1-16
126 changes: 126 additions & 0 deletions tests/test_kernel_cache_tag.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
"""The kernel cache tag must move whenever the cache image's contents would.

CI builds and pushes the cache image only when `just kernel-cache-tag` names a
tag that is not already published, and the gaming, nvidia and nvidia-gaming
builds take that image as their BASE_IMAGE. So a key that misses an input does
not fail anything -- it hands those three flavors an image built from the
previous recipe, and the only symptom is a kernel build that did not happen.

These tests copy the repository's hashed inputs into a scratch tree, mutate one
at a time, and assert the tag changes. The mutations are deliberately shallow
(a trailing comment) because the contract is "any edit, comments included", not
"any semantically significant edit".
"""

from __future__ import annotations

import shutil
import subprocess
import tempfile
import unittest
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
SCRIPT = ROOT / "scripts" / "kernel-cache-tag.sh"

# Every file the tag is required to cover, relative to the repository root.
HASHED_INPUTS = (
"Containerfile.kernel",
"scripts/install-ogc-kernel.sh",
"scripts/install-nvidia.sh",
"packages/hummingbird.repo",
"packages/fedora-44.repo",
)


def tag_of(root: Path) -> str:
"""Run the real script against `root` and return the tag it prints."""
result = subprocess.run(
["bash", str(root / "scripts" / "kernel-cache-tag.sh")],
capture_output=True,
text=True,
)
if result.returncode != 0:
raise AssertionError(f"kernel-cache-tag.sh failed:\n{result.stderr}")
return result.stdout.strip()


class KernelCacheTagTests(unittest.TestCase):
def setUp(self):
tmp = tempfile.TemporaryDirectory()
self.addCleanup(tmp.cleanup)
self.root = Path(tmp.name) / "utah"
(self.root / "scripts").mkdir(parents=True)
(self.root / "packages").mkdir(parents=True)
shutil.copy2(SCRIPT, self.root / "scripts" / "kernel-cache-tag.sh")
for rel in HASHED_INPUTS:
shutil.copy2(ROOT / rel, self.root / rel)
self.baseline = tag_of(self.root)

def test_tag_is_a_short_stable_hex_digest(self):
self.assertRegex(self.baseline, r"^[0-9a-f]{16}$")
self.assertEqual(self.baseline, tag_of(self.root), "tag is not deterministic")

def test_tag_matches_the_real_repository(self):
"""The scratch tree reproduces the tag the repository itself produces."""
self.assertEqual(self.baseline, tag_of(ROOT))

def test_every_hashed_input_moves_the_tag(self):
for rel in HASHED_INPUTS:
with self.subTest(input=rel):
path = self.root / rel
original = path.read_text()
path.write_text(original + "\n# cache-key probe\n")
self.addCleanup(path.write_text, original)
self.assertNotEqual(
self.baseline,
tag_of(self.root),
f"editing {rel} left the kernel cache tag unchanged, so CI would "
f"reuse the previously published cache image",
)
path.write_text(original)

def test_containerfile_recipe_body_moves_the_tag(self):
"""A recipe edit that leaves `ARG BASE_IMAGE=` alone must still rotate.

Hashing only the `ARG BASE_IMAGE=` line was the original defect: the
single RUN decides what lands in /cache-out and the final stage decides
what is copied out, and neither is on that line.
"""
path = self.root / "Containerfile.kernel"
original = path.read_text()
self.assertIn("/cache-out", original)
mutated = original.replace("/cache-out", "/cache-out-probe")
self.assertNotEqual(original, mutated)

arg_line = "ARG BASE_IMAGE="
before = [ln for ln in original.splitlines() if ln.startswith(arg_line)]
after = [ln for ln in mutated.splitlines() if ln.startswith(arg_line)]
self.assertEqual(before, after, "probe must not touch the base image pin")

path.write_text(mutated)
self.addCleanup(path.write_text, original)
self.assertNotEqual(
self.baseline,
tag_of(self.root),
"a Containerfile.kernel recipe change that leaves ARG BASE_IMAGE= "
"alone did not change the tag, so the published cache image would "
"be reused for a recipe that no longer builds it",
)

def test_base_image_pin_still_moves_the_tag(self):
"""Widening the key must not drop what it already covered."""
path = self.root / "Containerfile.kernel"
original = path.read_text()
mutated = "\n".join(
line.replace("sha256:", "sha256:0") if line.startswith("ARG BASE_IMAGE=") else line
for line in original.splitlines()
)
self.assertNotEqual(original, mutated, "no ARG BASE_IMAGE= digest to mutate")
path.write_text(mutated + "\n")
self.addCleanup(path.write_text, original)
self.assertNotEqual(self.baseline, tag_of(self.root))


if __name__ == "__main__":
unittest.main()
Loading