Skip to content
ocx
install

ocx_index

Operates on committed index snapshots, the reproducibility mechanism for floating tags next to @sha256: image index digests. The first argument selects the operation.

ocx_index(FIND [REQUIRED])
ocx_index(UPDATE_COMMAND <out-var> [INDEX <dir>] [PACKAGES <ref>...])

A snapshot is a directory owned by the ocx CLI. It holds <registry>/p/<repo>.json leaves that map tags to digests. Create and refresh it with ocx --index <dir> index update <package>.... Committing one next to your CMakeLists.txt as .ocx/ freezes every ocx_package tag resolution against it. The discovery ladder is described under ocx_package.

Changed in version 0.4. The leaves follow the layout of ocx 0.6. Regenerate a snapshot that an earlier CLI created with UPDATE_COMMAND.

ocx_index(FIND [REQUIRED])

Runs the .ocx/ discovery once and locks the result into OCX_INDEX for the current directory and below. The search goes upward from the calling directory and stops at the last project() source directory. A .ocx/ counts only when it holds a config.json or a <registry>/p/ directory. The .ocx/toolchain that ocx pull renders does not count.

REQUIRED

Turns “no snapshot found” into a configure error. Use it to fail fast at the top of a CMakeLists.txt instead of once per package. Without it, finding nothing is a quiet no-op.

The operation is not available in script mode, because script mode has no search bound. Set OCX_INDEX there instead.

ocx_index(UPDATE_COMMAND <out-var> [INDEX <dir>] [PACKAGES <ref>...])

Composes the command list that refreshes a snapshot and stores it in <out-var>. The list runs ocx --index <dir> index update <ref>... under the composed environment of the module. It carries no OCX_FROZEN, because index update refuses to run frozen. The operation works in project mode and in script mode, where execute_process can run the list.

INDEX <dir>

The snapshot to refresh. The default is the index in effect, which is OCX_INDEX, else the .ocx/ discovery.

PACKAGES <ref>...

The references to refresh. The default is the references of the preceding ocx_package calls frozen against that directory. A reference with a tag records only that tag, and a bare repository records every tag. The operation strips a @sha256: digest.

How the command runs is the caller’s choice: a build target, a test fixture or script mode. The module deliberately has no built-in target or ctest wiring. A test that rewrites a committed file would let CI paper over drift instead of failing. The freshness gate is the frozen configure itself, because a tag missing from the snapshot fails with the exit-81 refresh hint. Run the command, review the diff and commit.

The tested project examples/frozen_index locks the discovered snapshot and resolves a floating tag from it.

ocx_index(FIND REQUIRED)
ocx_package(NAME jq PACKAGE ocx.sh/jqlang/jq:latest BINS jq NO_ROOT)

The same project composes the refresh command and wraps it in a build target.

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
)

All commands are listed in the command reference.