Commands

Reference for the four commands that ocx.cmake defines. This page is generated from the .. command:: blocks in the module source.

ocx_bootstrap

Downloads a pinned ocx CLI release for the host and sets OCX_EXECUTABLE:

ocx_bootstrap([VERSION <version>] [TRIPLE <target-triple>])

No-op when OCX_EXECUTABLE already points at a binary of the requested version. The release row (URL + sha256) comes from the dist.json snapshot embedded in this file; OCX_INSTALL_DIST_URL fetches a mirrored manifest instead, OCX_INSTALL_MIRROR_URL rewrites the artifact download to <mirror>/<tag>/<filename>. The manifest sha256 is enforced either way. Binaries land in the per-machine OCX_BOOTSTRAP_CACHE (downloaded once per machine, shared by all build trees).

ocx_project

Provisions the toolchain of a workspace ocx.toml + ocx.lock:

ocx_project([NAME <name>] [TOML <ocx.toml>] [LOCK <ocx.lock>]
            [GROUPS <group>...] [BINS <tool>...]
            [PLATFORM <ocx-platform>] [PULL])

NAME (default PROJECT) prefixes the exported result variables, which are global cache-internal values usable from any directory:

OCX_<NAME>_RUN

Command-list prefix that composes the project environment and runs any tool on it (lazy: content materializes on first execution):

add_custom_command(... COMMAND ${OCX_PROJECT_RUN} jq . in > out)

OCX_<NAME>_RUN_<BIN>

Per-tool convenience command for every name in BINS. Entries are executable names on the composed environment (a package may ship several tools), not package references.

TOML defaults to OCX_PROJECT_FILE or the nearest ocx.toml between the calling directory and the last project() source dir; LOCK defaults to the sibling ocx.lock. ocx lock --check always runs (offline staleness gate); PULL (or the global OCX_PULL) materializes eagerly at configure time.

A foreign PLATFORM (default OCX_DEFAULT_PLATFORM) pulls that platform’s content from the same ocx.lock and exports OCX_<NAME>_PATHS / OCX_<NAME>_ENV_<KEY> instead of RUN commands (foreign binaries cannot execute; BINS is an error).

ocx_package

Provisions a single OCX package from an OCI registry:

ocx_package(NAME <name> PACKAGE <registry/repo[:tag][@sha256:...]>
            [PINS <platform>=sha256:<digest> ...]
            [INDEX <dir> | NO_INDEX] [BINS <tool>...]
            [PLATFORM <ocx-platform>] [PULL] [NO_ROOT])

Exports the same OCX_<NAME>_RUN / OCX_<NAME>_RUN_<BIN> command lists as ocx_project (re-entering ocx package exec, lazy by default). PINS maps ocx platform keys to per-platform manifest digests (as reported by ocx package install -p <platform>); the matching platform installs registry/repo@<digest>. BINS entries are executable names on the composed environment (a package may ship several tools), not package references.

Tag resolution is frozen against the first index snapshot in effect: the explicit INDEX <dir>, else the OCX_INDEX knob, else the nearest committed .ocx/ directory between the calling directory and the last project() source dir. NO_INDEX skips all three. A floating tag with no index in effect and no digest pin is a hard error unless OCX_ALLOW_FLOATING is set — reproducible first. Snapshots are created and refreshed deliberately (ocx --index <dir> index update <package>; see ocx_index for the composed refresh command).

With an index in effect the exported launchers run ocx --index <dir> --frozen and export both knobs into child processes: a find_ocx configure nested under such a launcher inherits the outer resolution mode unless it is given -DOCX_FROZEN= -DOCX_INDEX=.

With PULL (or the global OCX_PULL) the package is installed at configure time and <name>_ROOT (original case, CMP0074) is set to the package content root so a following find_package(<name>) / find_library searches the OCX-provisioned content — suppress with NO_ROOT. A foreign PLATFORM exports OCX_<NAME>_PATHS / OCX_<NAME>_ENV_<KEY> instead of RUN commands.

ocx_index

Operations on committed index snapshots — the reproducibility mechanism for floating tags, next to PINS and @sha256: 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 CLI-owned directory of <registry>/p/<repo>.json leaves mapping tags to digests, created and refreshed with ocx --index <dir> index update <package>.... Committing one next to your CMakeLists.txt as .ocx/ freezes every ocx_package tag resolution against it — see the discovery ladder there.

FIND

ocx_index(FIND [REQUIRED])

Runs the .ocx/ discovery once — upward from the calling directory, bounded by the last project() source dir — and locks the result into OCX_INDEX for the current directory and below. REQUIRED turns “no snapshot found” into a hard error (fail-fast at the top of a CMakeLists instead of per package). Without it, finding nothing is a quiet no-op. Not available in script mode (no search bound): set OCX_INDEX there instead.

UPDATE_COMMAND

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

Composes the command list that refreshes a snapshot: ocx --index <dir> index update <package>... under the module’s composed environment. INDEX defaults to the index in effect (OCX_INDEX, else the .ocx/ discovery). Without PACKAGES the packages are collected from the preceding ocx_package calls frozen against that directory; PACKAGES overrides the collection (full references are accepted — :tag / @sha256: are stripped). Works in project and script mode.

How the command runs is the caller’s choice — build target, test fixture, or script mode:

ocx_index(UPDATE_COMMAND refresh)
add_custom_target(index-update COMMAND ${refresh} VERBATIM)
# or, in script mode:
execute_process(COMMAND ${refresh} COMMAND_ERROR_IS_FATAL ANY)

Deliberately 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 — a tag missing from the snapshot fails with the exit-81 refresh hint. Run the command, review the diff, commit.