- integrations
- CMake
- Everyday
- Pin and freeze tag resolution
Pin and freeze tag resolution
A configure stopped because ocx_package got a floating tag such as :latest and nothing fixes what that tag means.
A moving tag builds one tool version today and another next month, and a host find_program has the same problem with whatever is installed.
FetchContent hashes the sources it downloads, but a tool tag has no such hash until you record one.
This page freezes the tag with an index snapshot or an image index digest, refreshes it on purpose, and runs a frozen configure.
ocx_project builds are already frozen by ocx.lock, so this page covers ocx_package.
See why the configure stopped
Section titled “See why the configure stopped”The error names the package and lists three ways out.
The recording shows it for a jq:latest package.
The three ways are a committed snapshot, an image index digest, or OCX_ALLOW_FLOATING=ON.
The last one accepts drift and belongs in throwaway experiments only.
Reproducible first explains the reasoning.
Commit an index snapshot
Section titled “Commit an index snapshot”A snapshot is a directory named .ocx/ that records what each tag resolved to.
Create it from the directory that holds your CMakeLists.txt, once per tag you use, and commit it like a lock file.
The command for jq is ocx --index .ocx index update ocx.sh/jqlang/jq:latest.
A bare repository, without :latest, records every tag the registry lists and makes a larger diff.
Every ocx_package call finds the nearest .ocx/ directory by itself.
ocx_index(FIND REQUIRED) makes that explicit and stops the configure when the snapshot is missing.
# Fail-fast when the snapshot is missing, and lock the discovered .ocx/# into OCX_INDEX for this directory and below. (Each ocx_package would# also discover it on its own - FIND REQUIRED makes the intent explicit.)ocx_index(FIND REQUIRED)
# Floating tag, no INDEX argument, no digests: resolves frozen from the# committed snapshot (.ocx/ocx.sh/p/jqlang/jq.json).ocx_package(NAME jq PACKAGE ocx.sh/jqlang/jq:latest BINS jq NO_ROOT)Refresh the snapshot on purpose
Section titled “Refresh the snapshot on purpose”Nothing updates a snapshot by itself, because a silent refresh would hide drift.
ocx_index(UPDATE_COMMAND) composes the refresh command, and you decide how it runs.
Here it is a build target.
# Deliberate refresh flow: the module composes the command, the caller# decides how it runs - here a build target. Never wired up automatically:# a refresh that runs on its own would paper over drift instead of# surfacing it.ocx_index(UPDATE_COMMAND refresh)add_custom_target( index-update COMMAND ${refresh} COMMAND ${CMAKE_COMMAND} -E echo "index snapshot refreshed - review the diff and commit the result" VERBATIM)- Run
cmake --build build --target index-update. - Review the diff of
.ocx/. - Commit the result.
The composed command runs without frozen mode.
It works while OCX_FROZEN is set.
A tag that is missing from the snapshot makes the next frozen configure fail with exit code 81 and a refresh hint.
This happens when the call has BINS or PULL, because those run ocx at configure time.
Without them the first build step fails instead, as the frozen configure explains.
Run a frozen configure
Section titled “Run a frozen configure”Set OCX_FROZEN to a truthy value such as 1 before the first configure of a build directory.
Every ocx call then refuses a tag that is neither in the snapshot nor in the lock, with exit code 81.
Frozen mode is not an offline mode, because ocx may still fetch content it has pinned.
Each OCX_* setting is stored on the first configure and stays for that build directory.
Use a fresh build directory when you change it.
To build with no network, fill the local store first.
Configure once online with -DOCX_PULL=ON, because a lazy configure leaves the store empty.
Then configure a fresh directory with OCX_FROZEN=1 and OCX_OFFLINE=1.
Lazy versus eager explains the difference.
Point at a snapshot elsewhere
Section titled “Point at a snapshot elsewhere”Give ocx_package an INDEX directory to freeze against a snapshot outside the project tree.
NO_INDEX skips every snapshot for one call.
ocx_package( NAME jq_frozen PACKAGE ocx.sh/jqlang/jq:latest BINS jq NO_ROOT INDEX "${CMAKE_CURRENT_SOURCE_DIR}/index")Next steps
Section titled “Next steps”- Pin an image index digest fixes a tag without a snapshot directory.
- Add or change a pinned tool covers
ocx_projectand its lock. - Route package pulls through a mirror covers mirrors and credentials.
ocx_indexlists every keyword.