- integrations
- CMake
- Troubleshooting
- Fix a failing configure
Fix a failing configure
Each entry below starts with the message you see, then names the cause and the fix.
A failing ocx call reports its exit status and ends with a hint: line.
Exit codes maps every status to a cause.
For a duplicate NAME or a second copy of the module, see Fix a module conflict.
Error: the lock check fails
Section titled “Error: the lock check fails”find_ocx: checking <dir>/ocx.toml against its lockfile failed (exit 65): ocx --project <dir>/ocx.toml lock --checkocx.lock does not match ocx.toml; run `ocx lock` to update ithint: run 'ocx lock' next to <dir>/ocx.toml and commit the updated ocx.lockThis issue occurs when ocx.toml changed after ocx.lock was written, and the exit code is 65.
ocx_project runs ocx lock --check on every configure, which is an offline staleness gate:
include(ocx)
ocx_project(NAME STALE)Run ocx lock next to ocx.toml, review the diff and commit ocx.lock.
A missing or unusable lock gives exit 78 and these lines:
find_ocx: checking <dir>/ocx.toml against its lockfile failed (exit 78): ocx --project <dir>/ocx.toml lock --checkocx.lock not found at <dir>/ocx.lock; run `ocx lock` to create ithint: no ocx.lock next to <dir>/ocx.toml, a version 2 lock, or unusable config - run 'ocx lock' and commit it, or read the message aboveThe first case is ocx.toml with no ocx.lock beside it.
A lock file of format version 2 gives the same exit code and a different second line:
<dir>/ocx.lock: unsupported ocx.lock version 2; regenerate with `ocx lock`A lock file in a format that the configure’s ocx does not know is rejected the same way.
Run ocx lock with the binary that the configure uses, then commit ocx.lock.
Two entry points lists which binary that is.
On a machine with no ocx, write the first lock with the downloaded CLI.
Error: a floating tag stops the configure
Section titled “Error: a floating tag stops the configure”find_ocx: ocx_package DRIFTY: 'ocx.sh/jqlang/jq:latest' is floating and no index snapshot is in effect - resolution is not reproduciblefix (pick one): commit a snapshot ('ocx --index .ocx index update ocx.sh/jqlang/jq:latest' next to your CMakeLists, or set OCX_INDEX); pin the image index digest with @sha256:; or accept drift explicitly with -DOCX_ALLOW_FLOATING=ONThis issue occurs when a package uses a floating tag such as :latest, and neither an index snapshot nor a digest fixes it:
include(ocx)ocx_package(NAME DRIFTY PACKAGE ocx.sh/jqlang/jq:latest)find_ocx is reproducible first, so it refuses to resolve the tag live. Pick one fix:
- Commit an index snapshot. Run
ocx --index .ocx index update ocx.sh/jqlang/jq:latestin the directory that holdsCMakeLists.txt, then commit.ocx. - Pin the image index digest. Use
PACKAGE ocx.sh/jqlang/jq:latest@sha256:<index digest>, and read the digest withocx package inspect ocx.sh/jqlang/jq:latest. - Accept drift for one run. Configure with
-DOCX_ALLOW_FLOATING=ON. APULLcall then logs how to pin the tag, and a lazy call only warns that the tag can drift.
Pin and freeze tag resolution walks through the first two.
A call that still passes the removed PINS keyword stops with PINS was removed.
Use the second fix, and Move from 0.3 to 0.4 shows the before and after.
If the call stops earlier with NAME and PACKAGE are required, add NAME.
A one-line ocx_package(PACKAGE ...) copied from an article often lacks it.
Error: a nested configure fails with the exit-81 refresh hint
Section titled “Error: a nested configure fails with the exit-81 refresh hint”find_ocx: installing ocx.sh/kitware/cmake:3.31 failed (exit 81): ocx --index <outer index> --frozen --format json package install ocx.sh/kitware/cmake:3.31failed to install package: ocx.sh/kitware/cmake:3.31 — frozen mode refused to resolve unpinned reference 'ocx.sh/kitware/cmake:3.31'; run `ocx index update` or pin a digesthint: package not in the committed index snapshot - refresh it with 'ocx --index <outer index> index update ocx.sh/kitware/cmake:3.31'This issue occurs when a find_ocx configure runs inside an ocx launcher, such as an ExternalProject, ctest --build-and-test or a superbuild.
With ocx 0.6.5 and earlier, a launcher with an index or frozen mode exports OCX_FROZEN and OCX_INDEX into child processes.
That covers ocx package exec --frozen and every OCX_<NAME>_RUN list of an ocx_package that has an index snapshot.
The inner configure stores those values as if you had set them, but the outer index does not list the inner packages.
A launcher without an index or frozen mode, such as ocx exec for a project, exports neither variable.
The error does not occur with ocx 0.6.6, which passes root flags in __OCX_ENV_STATE, because find_ocx removes it.
With ocx 0.6.5 and earlier, pass both variables empty to the nested configure.
An empty OCX_INDEX drops the inherited value without hiding a snapshot that the inner project commits itself.
The repository’s own test harness does this for every fixture it configures:
set(common_options "-DCMAKE_MODULE_PATH=${CMAKE_SOURCE_DIR}" "-DOCX_FROZEN=" "-DOCX_INDEX=")On a command line, append the same two options:
cmake -DOCX_FROZEN= -DOCX_INDEX= ...Error: a BINS name does not resolve
Section titled “Error: a BINS name does not resolve”find_ocx: ocx_project TOOLS (<dir>/ocx.toml): BINS jqq: not a declared binary or entrypointdeclared: jqhint: BINS names are executable names, check the spellingThis issue occurs when BINS lists a name that the package or the selected groups do not expose.
The message names the unknown entry and lists the names that are declared.
ocx_package prints the same message with its package reference in place of the ocx.toml path.
A name that exists only in a group that you did not select gets a different message:
find_ocx: ocx_project TOOLS (<dir>/ocx.toml): BINS shellcheck: declared only in a group that was not requestedhint: add the group to GROUPS (the [tools] table is the group 'default'), e.g. GROUPS default <group>Two causes cover most cases:
- The name is misspelled. Compare it with the names that the package exposes.
- The tool lives in a group other than the default one.
ocx_projectselects only the default group unlessGROUPSlists more, soGROUPS lintalone also drops the top-level tools.
Name the default group next to the others:
ocx_project(NAME TOOLS GROUPS default lint BINS jq shellcheck)find_ocx checks BINS against the packages for this reason.
Without the check, a copy of the tool on the host PATH would hide the mistake and the build would pass on your machine only.
Two cases skip the check and print a status line instead:
find_ocx: <what>: BINS not validated (OCX_OFFLINE and the package is not in the local store)find_ocx: <what>: BINS <names> not validated (the package does not declare all of its binaries)A skipped check means a wrong name fails later, when a build step runs the tool.