Variables

Reference for the OCX_* variables of ocx.cmake. This page is generated from the .. variable:: blocks in the module source.

CMake support for OCX — the OCI-backed package manager. Bootstraps the pinned ocx CLI (sha256-enforced, corporate-mirror aware) and provisions tools through it. find_ocx deliberately never re-implements OCX internals in CMake: all resolution goes through the ocx binary; the durable contracts are ocx.lock digests and the OCI manifests.

Vendor this file together with Findocx.cmake into your project (e.g. cmake/), then:

list(APPEND CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake)
include(ocx)

ocx_project()                    # toolchain from ./ocx.toml + ./ocx.lock
ocx_package(NAME jq PACKAGE ocx.sh/jqlang/jq:latest)   # frozen via ./.ocx snapshot

Requires CMake 3.19 (string(JSON), file(ARCHIVE_EXTRACT)). Include after project().

Resolution is reproducible-first: a floating tag resolves through a committed index snapshot (the nearest .ocx/ directory, discovered like ocx.toml; create it with ocx --index .ocx index update <package>) or through digest pins — with neither, the configure fails (OCX_ALLOW_FLOATING is the explicit escape hatch).

include(ocx) itself is passive — it only defines commands and snapshots the OCX_* knobs. The first provisioning call (ocx_project, ocx_package, or an explicit ocx_bootstrap) resolves the CLI: OCX_EXECUTABLE when set, else an ocx on PATH, else it downloads the pinned, sha256-verified CLI into the per-machine cache. OCX_BOOTSTRAP=ALWAYS skips the PATH search (hermeticity: every machine runs the identical pinned binary); OCX_BOOTSTRAP=OFF forbids the implicit download entirely. An explicit ocx_bootstrap call always provisions the pin.

Corporate mirrors and behavior knobs are plain OCX_* variables. Each one follows the snapshot pattern: if the CMake variable is unset but the environment variable is set at the first configure, the value is snapshotted into the cache and stays sticky for the build directory (override with -DVAR=..., clear with -DVAR=).

OCX_EXECUTABLE

Path to the ocx CLI to run everything through. Snapshotted from the environment like every other knob (CI: export OCX_EXECUTABLE=$(which ocx) needs no -D); when unset, the first provisioning call bootstraps the pin.

OCX_INSTALL_DIST_URL

Fetch the ocx release manifest (dist.json) from a mirror instead of the snapshot embedded in this file.

OCX_INSTALL_MIRROR_URL

Rewrite the ocx binary download to <mirror>/<tag>/<filename>. The manifest sha256 is still enforced — a mirror can move bytes, not change them.

OCX_INSTALL_VERSION

ocx CLI version to bootstrap (default: the version pinned with this find_ocx release). Same knob as the setup.ocx.sh installer.

OCX_BOOTSTRAP

Implicit-bootstrap policy for the first provisioning call when OCX_EXECUTABLE is not set. Unset or ON (default): use an ocx found on PATH, bootstrap the pinned CLI when there is none. ALWAYS: skip the PATH search — every machine runs the identical pinned binary (hermetic mode; pair with OCX_INSTALL_VERSION). OFF: never download — OCX_EXECUTABLE or a PATH ocx is required, anything else is a hard configure error (for environments that forbid configure-time downloads). Inside Findocx.cmake the same variable is the opt-in for the bootstrap fallback (find modules discover by default).

OCX_DEFAULT_PLATFORM

Default PLATFORM for ocx_project / ocx_package (empty = host).

OCX_INDEX

Committed index snapshot directory freezing tag resolution for every ocx_package without an explicit INDEX. When unset, each call discovers the nearest .ocx/ directory between its calling directory and the last project() source dir instead (ocx_index FIND runs that discovery once and locks the result into this variable). Clearing with -DOCX_INDEX= neutralizes a value inherited from an outer ocx launcher without vetoing the project’s own committed snapshot.

OCX_ALLOW_FLOATING

Reproducibility escape hatch. By default a floating tag with no index snapshot in effect and no digest pin is a hard configure error — ocx is reproducible-first. ON downgrades that to the pre-0.3 behavior (live resolution, drift warning); useful transiently to print the digests that seed PINS.

OCX_BOOTSTRAP_CACHE

Cache directory for bootstrapped ocx binaries. Default: per-machine — %LOCALAPPDATA%/find_ocx (Windows), $XDG_CACHE_HOME/find_ocx, ~/.cache/find_ocx, falling back to <build>/_ocx/cache when no home directory exists. Point it into the workspace on CI runners where the home directory is unreliable (and restore it with your CI cache).

OCX_PROJECT_FILE

Default ocx.toml for ocx_project when no TOML argument is given.

OCX_PULL

Force eager materialization (PULL) for every ocx_project/ocx_package call — useful in CI to fail fast and warm caches.

OCX_REFRESH

One-shot: bypass the reconfigure memoization and re-execute ocx.

OCX_SELF_UPDATE_VERSION

find_ocx release tag to self-update the vendored ocx.cmake and Findocx.cmake to (vX.Y.Z; the v is optional). Default: the latest release, discovered via the GitHub releases API. Script mode only:

cmake [-DOCX_SELF_UPDATE_VERSION=v0.3.0] -P cmake/ocx.cmake

replaces this file (and a sibling Findocx.cmake when present) in place, verified against the release SHA256SUMS.

OCX_SELF_UPDATE_URL

Fetch the find_ocx release files from <url>/<tag>/<filename> instead of GitHub — same rewrite shape as OCX_INSTALL_MIRROR_URL. Requires an explicit OCX_SELF_UPDATE_VERSION (mirrors do not serve the releases API); the mirrored SHA256SUMS stays the trust root.

Passthrough and credentials

Passthrough variables forwarded to every ocx invocation when set (same set as rules_ocx): OCX_HOME, OCX_MIRRORS, OCX_INSECURE_REGISTRIES, OCX_OFFLINE, OCX_FROZEN, OCX_REMOTE, OCX_JOBS, OCX_INDEX, OCX_DEFAULT_REGISTRY. Clearing a knob with -DVAR= actively removes it from the environment of every ocx invocation. That is the opt-out for launcher inheritance: ocx launchers (ocx run, frozen package exec — including the OCX_<NAME>_RUN command lists this module exports) export OCX_FROZEN and OCX_INDEX into child processes, so a find_ocx configure nested inside one (ExternalProject, test harnesses) inherits the outer resolution mode unless it is given -DOCX_FROZEN= -DOCX_INDEX=.

OCX_AUTH_<REGISTRY>_{TYPE,USER,TOKEN} credentials are deliberately never snapshotted into the cache — export them in the environment and reconfigure after changing them.