- integrations
- CMake
- Concepts
- How find_ocx works
How find_ocx works
This page explains what find_ocx runs at configure and build time, and why every resolution step stays inside the ocx binary.
Why it never re-implements ocx
Section titled “Why it never re-implements ocx”The OCI protocol, registry authentication and the package store all belong to ocx.
If the module copied them into CMake, every ocx change would need a matching CMake change.
So find_ocx runs the ocx binary for every resolution and parses its JSON.
The durable contracts are the ocx.lock digests and the OCI manifests.
A missing capability becomes an issue against ocx, not a workaround in this module.
What runs, in order
Section titled “What runs, in order”include(ocx)is passive. It defines commands and fetches nothing.- The first provisioning call picks the CLI. It uses
OCX_EXECUTABLE, then anocxonPATH, then a pinned bootstrap that is sha256-verified and cached once per machine. The first configure of a build tree prints the choice unless you setOCX_EXECUTABLE. Two entry points lists the rules. - Every
ocxcall goes through one wrapper. It sets a fixed environment and retries exit 75 twice on the calls that download. Any other non-zero exit becomes a configure error with a hint. Environment and config lists the environment, and Exit codes lists the hints. ocx_projectrunsocx lock --checkas an offline staleness gate.ocx_packageresolves its reference through the index ladder.- Eager mode adds
ocx pullorocx package install. A foreignPLATFORMalso composes the environment. A project usesocx env --pinnedand a package usesocx package env, so the paths do not depend on the platform ocx rendered last. - Each name in
BINSis checked against what the package declares, usingocx inspect --closure. A name that does not exist stops the configure. - The call exports
OCX_<NAME>_RUNand the other result variables. - With unchanged inputs, a later configure skips steps 4 to 7. Lazy versus eager explains how.
What a command list is
Section titled “What a command list is”OCX_<NAME>_RUN is a plain CMake list.
For a project it re-enters ocx exec, and for a package it re-enters ocx package exec.
No wrapper script is written, so the list works in add_custom_command, in add_test, and with generator expressions.
The content downloads on first execution into the shared, content-addressed OCX_HOME store.
What is shared
Section titled “What is shared”The bootstrap cache and the OCX_HOME store belong to the machine, not to the build tree.
A package is fetched once per machine, and every build tree reuses it.
ocx_project also writes a .ocx/toolchain directory next to ocx.toml.
It holds links that ocx renders, and ocx writes its own .gitignore inside it.
That directory is not the committed .ocx/ index snapshot described in Reproducible first.
Where to go next
Section titled “Where to go next”- Two entry points explains which binary runs.
- Lazy versus eager explains when the network is touched.
- Reproducible first explains why a floating tag is an error.
- Environment and config explains which
OCX_*variables reach ocx.