- integrations
- CMake
- Concepts
- Reproducible first
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.
Why a floating tag is an error
Section titled “Why a floating tag is an error”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.
Three ways to fix a tag
Section titled “Three ways to fix a tag”| 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>.
The index ladder
Section titled “The index ladder”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:
- The
INDEX <dir>argument. - The
OCX_INDEXvariable. - The nearest
.ocx/directory between the calling directory and the lastproject()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.
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)Snapshots never refresh themselves
Section titled “Snapshots never refresh themselves”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.
The frozen configure
Section titled “The frozen configure”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.9failed 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 digesthint: 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.
Where the digests are visible
Section titled “Where the digests are visible”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.
Related pages
Section titled “Related pages”- Pin and freeze tag resolution sets this up step by step.
- Error: a floating tag stops the configure fixes the failure.
- Lazy versus eager explains when the network is touched.