- integrations
- CMake
- ocx_index
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.
UPDATE_COMMAND
Section titled “UPDATE_COMMAND”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.
Examples
Section titled “Examples”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.