Skip to content
ocx
install

Reproducible first

This page explains why find_ocx fails a configure on an unpinned floating tag, and how locks, snapshots and index digests fix resolution.

A floating tag such as :latest or :3.31 names whatever the registry holds today. Two machines, or the same machine a week apart, can resolve it to different bytes. A configure that works today and changes tomorrow is harder to debug than one that stops at once. So find_ocx refuses to resolve a floating tag live. The configure fails unless something fixes what the tag means.

Pin Where it lives What it fixes How you refresh it
Lock file ocx.lock next to ocx.toml Every tool of ocx_project, per platform ocx lock, then commit
Index snapshot A committed .ocx/ directory Every tag of ocx_package that the snapshot lists ocx_index(UPDATE_COMMAND), then commit
Image index digest @sha256: in PACKAGE One reference, every platform Edit the digest by hand

An @sha256: digest of the image index pins all platforms at once, and ocx selects the leaf for the building platform, features included, and verifies it. A digest of one leaf manifest would skip that selection, so find_ocx offers no keyword for it. For one pinned line that works on every platform, use PACKAGE ocx.sh/jqlang/jq:1.8.2@sha256:<index digest>.

An index snapshot is a directory of <registry>/p/<repo>.json files that the CLI owns. You commit it like a lock file. Each ocx_package finds its snapshot in this order:

  1. The INDEX <dir> argument.
  2. The OCX_INDEX variable.
  3. The nearest .ocx/ directory between the calling directory and the last project() source directory.

NO_INDEX skips all three. A .ocx/ directory counts only when it holds a config.json or a <registry>/p/ directory. The .ocx/toolchain directory that ocx_project writes is therefore never mistaken for a snapshot. A vendored subproject with its own project() gets its own bound, so snapshots do not leak across projects.

ocx_index(FIND REQUIRED) runs that discovery once, fails fast when nothing is committed, and locks the result into OCX_INDEX.

CMakeLists.txt
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)

ocx_index(UPDATE_COMMAND <var>) composes the refresh command and leaves it to you to run. A build target, a script or a CI job that opens a pull request all work. Nothing runs it on its own, because a refresh that runs by itself would hide drift instead of showing it. Run the command, review the diff of the .ocx/ files and commit.

The refresh command runs without OCX_FROZEN, because ocx index update cannot run in frozen mode. It names the tags your calls use. By hand, a bare ocx --index .ocx index update <repo> records every tag of the repository, and <repo>:<tag> records only that tag.

A frozen configure is the freshness gate. Set OCX_FROZEN=1, and every ocx call resolves only from the lock, the snapshot or a digest. A tag the snapshot does not list stops the configure with exit 81 when the call has BINS or PULL, because those run ocx at configure time:

find_ocx: inspecting ocx_package X (ocx.sh/jqlang/jq:9.9.9) failed (exit 81): ocx --index <dir>/.ocx --frozen --format json package inspect --closure ocx.sh/jqlang/jq:9.9.9
failed to inspect package: ocx.sh/jqlang/jq:9.9.9 — frozen mode refused to resolve unpinned reference 'ocx.sh/jqlang/jq:9.9.9'; run `ocx index update` or pin a digest
hint: package not in the committed index snapshot - refresh it with 'ocx --index <dir>/.ocx index update ocx.sh/jqlang/jq:9.9.9'

A lazy call without BINS runs no ocx at configure time, so the same refusal comes at the first build step that runs the tool.

OCX_FROZEN is a site variable. The first configure of a build directory snapshots it into the cache, so use a fresh build directory to try it. Environment and config explains the stickiness.

A package with an index in effect already carries --index <dir> --frozen in its OCX_<NAME>_RUN list. Setting OCX_FROZEN extends the same rule to the configure itself. To prepare an offline build, fetch with PULL while online, as Lazy versus eager shows.

The snapshot files hold every digest, and the lock file holds those of a project. An eager install of a floating tag also logs how to pin it. A lazy configure of a floating tag only warns that the tag can drift, and it prints no digest. ocx package inspect <ref> prints the image index digest of a tag.

The escape hatch is -DOCX_ALLOW_FLOATING=ON, which downgrades the error to a drift warning. It is useful for one run, to resolve a tag before you pin it.