Pin and freeze tag resolution

Use a committed .ocx/ index snapshot or per-platform digests so a floating tag such as :latest resolves the same way on every machine. Without one of them, a floating tag is a hard configure error.

Commit an index snapshot

Create the snapshot for the packages you use and commit it like a lock file.

ocx --index .ocx index update ocx.sh/jqlang/jq ocx.sh/kitware/cmake
git add .ocx

Then fail fast in CMakeLists.txt when the snapshot is missing.

examples/frozen_index/CMakeLists.txt

# 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)

Each ocx_package call discovers the nearest .ocx/ directory by itself. The ocx_index(FIND REQUIRED) call only makes the intent explicit.

Refresh the snapshot on purpose

Snapshots are never updated automatically. Compose the refresh command and decide how it runs. Here it is a build target.

examples/frozen_index/CMakeLists.txt

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)

1. Run cmake --build build --target index-update.
2. Review the diff of .ocx/.
3. Commit the result.

A tag that is missing from the snapshot makes the next frozen configure fail with a refresh hint.

Pin per-platform digests instead

Pin a manifest digest for each platform when you want no snapshot directory. Nothing is downloaded until the first build-time execution.

examples/package/CMakeLists.txt

ocx_package(NAME jq_pinned PACKAGE ocx.sh/jqlang/jq:1.8.2 BINS jq NO_ROOT
  PINS
    "linux/amd64=sha256:913ff41f5e643a73c17a2e560e349d8eea255f50b293156e58da15b957baacae"
    "linux/arm64=sha256:81b771e5c4e9b70cfeb19c825ca2b00a5078c238e7d3175eee9d772cedda006b"
    "darwin/amd64=sha256:f750c91d28769d12298ba9a4c10340152fcbdd48c48102bf275c21d736cc72a2"
    "darwin/arm64=sha256:c5cf10597aacad9b7925f937c966ec72145ea6a40f7f7ef4cac11f90c43130b1"
    "windows/amd64=sha256:bab93861d95a25d33163cc9499cb17bb109028d6537ca55b8427af21c1fdc989"
)

Get the digests from ocx package install -p <platform> or from the ocx.lock of a project. You can also print them once with a floating pull, which needs the explicit escape hatch.

examples/package/CMakeLists.txt

set(OCX_ALLOW_FLOATING ON)
ocx_package(NAME jq PACKAGE ocx.sh/jqlang/jq:latest PULL)
unset(OCX_ALLOW_FLOATING)

Point at a snapshot elsewhere

Use INDEX to freeze against any directory.

examples/package/CMakeLists.txt

ocx_package(NAME jq_frozen PACKAGE ocx.sh/jqlang/jq:latest BINS jq NO_ROOT
  INDEX "${CMAKE_CURRENT_SOURCE_DIR}/index")

For why a floating tag is an error, see Reproducible first. Needs addressed: problem 3 of the use-case research.