- integrations
- CMake
- Reference
- Variables
Variables
Reference for the OCX_* variables of ocx.cmake.
This page is generated from the .. variable:: blocks in the module source.
Setting a variable
Section titled “Setting a variable”The plain OCX_* variables below configure mirrors and behavior. Each one follows the snapshot pattern. A variable that is unset in CMake but set in the environment at the first configure is copied into the cache. The cached value then stays for the build directory. Override it with -DVAR=... and clear it with -DVAR=.
OCX_EXECUTABLE
Section titled “OCX_EXECUTABLE”Path of the ocx CLI that runs every command. The environment value is snapshotted like every other variable, so CI needs no -D. export OCX_EXECUTABLE=$(which ocx) is enough. A path that does not exist is a configure error, and it never falls back to PATH. An empty value, as in -DOCX_EXECUTABLE=, counts as unset.
When the variable is unset, the first provisioning call looks on PATH and then bootstraps the pinned CLI. The module remembers a path that it chose itself and chooses again on every configure. A changed OCX_INSTALL_VERSION, a changed pin or OCX_BOOTSTRAP=ALWAYS therefore reaches an existing build directory. A path that you set stays as it is.
The value must not contain ;, which a CMake list cannot carry.
OCX_INSTALL_DIST_URL
Section titled “OCX_INSTALL_DIST_URL”URL of an ocx release manifest (dist.json) that replaces the snapshot embedded in ocx.cmake. A manifest not named <sha256>.json is fetched unverified. The DIST_MANIFEST keyword of ocx_bootstrap takes precedence over this variable.
Changed in version 0.4. A manifest named <sha256>.json is verified against that digest.
OCX_INSTALL_MIRROR_URL
Section titled “OCX_INSTALL_MIRROR_URL”Base URL that rewrites the ocx binary download to <mirror>/<tag>/<filename>. The manifest sha256 is still enforced, so a mirror can move bytes but cannot change them.
OCX_INSTALL_CA_BUNDLE
Section titled “OCX_INSTALL_CA_BUNDLE”Path of a PEM CA bundle that the CLI download trusts instead of the system store. Use it for a mirror behind a TLS-intercepting proxy. A relative path resolves against the top-level source directory. A path that is not a file is a configure error, checked on every configure that provisions or runs the CLI.
The module passes the bundle as TLS_CAINFO to the manifest and archive downloads of ocx_bootstrap and to ocx_self_update. Every ocx call also receives it as OCX_EXTRA_CA_CERTS, unless OCX_EXTRA_CA_CERTS is set. An empty -DOCX_EXTRA_CA_CERTS= counts as set and removes the variable. The setup.ocx.sh installer has the same variable.
New in version 0.4.
OCX_INSTALL_VERSION
Section titled “OCX_INSTALL_VERSION”ocx CLI version to bootstrap. The default is the version pinned by this find_ocx release. The setup.ocx.sh installer has the same variable.
OCX_BOOTSTRAP
Section titled “OCX_BOOTSTRAP”Policy for the implicit bootstrap of the first provisioning call when OCX_EXECUTABLE is not set. The values are the following, in any case. The CMake booleans count as ON and OFF, and any other value is a configure error.
ON
The default, also when the variable is unset or empty. Use an ocx found on PATH and bootstrap the pinned CLI when there is none.
ALWAYS
Skip the PATH search, so every machine runs the identical pinned binary. Pair it with OCX_INSTALL_VERSION.
OFF
Never download. OCX_EXECUTABLE or an ocx on PATH is required, and anything else is a configure error. Use it where configure-time downloads are forbidden.
Inside Findocx.cmake the same variable opts in to the bootstrap fallback, because find modules discover by default. An empty value counts as unset there too, which means OFF.
OCX_DEFAULT_PLATFORM
Section titled “OCX_DEFAULT_PLATFORM”Default PLATFORM for ocx_project and ocx_package. The value is one ocx platform such as linux/arm64, and the empty default means the host. A ;-list is a configure error. Call the command once per platform under its own NAME instead.
OCX_INDEX
Section titled “OCX_INDEX”Directory of the committed index snapshot that freezes tag resolution for every ocx_package without an explicit INDEX. When the variable is unset, each call discovers the nearest .ocx/ directory between its calling directory and the last project() source directory. ocx_index FIND runs that discovery once and locks the result into this variable.
Clearing the variable with -DOCX_INDEX= neutralizes a value inherited from an outer ocx launcher. The project’s own committed snapshot is still discovered.
OCX_ALLOW_FLOATING
Section titled “OCX_ALLOW_FLOATING”Reproducibility escape hatch. A floating tag with no index snapshot in effect and no digest pin is a configure error by default. ON downgrades the error to live resolution with a drift warning. Use it transiently, then pin the tag with an index snapshot or an @sha256: image index digest.
OCX_BOOTSTRAP_CACHE
Section titled “OCX_BOOTSTRAP_CACHE”Cache directory for bootstrapped ocx binaries, where a relative path resolves against the top-level source directory. The default is per machine: %LOCALAPPDATA%/find_ocx on Windows, else $XDG_CACHE_HOME/find_ocx, else ~/.cache/find_ocx, else <build>/_ocx/cache. Point the variable into the workspace on CI runners where the home directory is unreliable, and restore it with the CI cache. The module copies a binary in atomically and runs a cached one once per configure. It downloads again a binary that does not run or reports another version.
OCX_PROJECT_FILE
Section titled “OCX_PROJECT_FILE”Default ocx.toml for ocx_project when the call has no TOML argument.
OCX_PULL
Section titled “OCX_PULL”Forces eager materialization, as the PULL keyword does, for every ocx_project and ocx_package call. Use it in CI to fail fast and to warm caches.
OCX_REFRESH
Section titled “OCX_REFRESH”One-shot switch that bypasses the reconfigure memoization and runs ocx again. The module clears it at the end of the configure.
OCX_SELF_UPDATE_VERSION
Section titled “OCX_SELF_UPDATE_VERSION”find_ocx release tag that ocx_self_update installs, written vX.Y.Z. The leading v is optional. The default is the latest release, found through the GitHub releases API.
OCX_SELF_UPDATE_URL
Section titled “OCX_SELF_UPDATE_URL”Base URL that serves the find_ocx release files as <url>/<tag>/<filename> instead of GitHub. It has the same rewrite shape as OCX_INSTALL_MIRROR_URL. It requires an explicit OCX_SELF_UPDATE_VERSION, because mirrors do not serve the releases API. The mirrored SHA256SUMS file stays the trust root.
Environment classes
Section titled “Environment classes”New in version 0.4.
Every ocx call gets its environment from four classes of OCX_* variable. The class decides what an ambient value does, so a variable exported in the shell or by an outer launcher cannot change a build silently.
| Class | Variables | Behavior |
|---|---|---|
| site | OCX_HOME OCX_MIRRORS OCX_INSECURE_REGISTRIES OCX_OFFLINE OCX_FROZEN OCX_REMOTE OCX_JOBS OCX_INDEX OCX_DEFAULT_REGISTRY OCX_MANAGED_CONFIG OCX_PATCHES OCX_EXTRA_CA_CERTS |
Snapshotted from the environment at the first configure and forwarded to every call. -DVAR= removes the variable from every call. |
| translucent | OCX_CONFIG OCX_PATCH_SNAPSHOT OCX_NO_CONFIG OCX_SIGSTORE_TRUSTED_ROOT |
The ambient value passes through unchanged. A keyword overrides it: CONFIG, PATCH_SNAPSHOT and NO_CONFIG of ocx_project and ocx_package (per command), SIGSTORE_TRUSTED_ROOT of ocx_policy. |
| explicit | OCX_NO_VERIFY OCX_ALLOW_YANKED |
Removed from every call. Only ocx_policy sets them. |
| pinned | OCX_PROJECT OCX_GLOBAL OCX_QUIET OCX_NO_PROJECT OCX_NO_CONFIG_REFRESH OCX_NO_CONSENT OCX_SELF_UPDATE |
Forced to a fixed value on every call (OCX_PROJECT and OCX_GLOBAL unset, OCX_QUIET=0, OCX_SELF_UPDATE=manual), so find_ocx can parse what ocx prints. |
The configure-time calls and the exported OCX_<NAME>_RUN command lists carry the same environment. A value, a path or a site variable must not contain ;, and the module stops the configure when one does. Changing OCX_CONFIG or a config file runs ocx again, because their content is part of the reconfigure fingerprint.
A find_ocx configure nested in an ocx launcher does not inherit its --frozen, --offline or --index under ocx 0.6.6. Set OCX_FROZEN, OCX_OFFLINE or OCX_INDEX in the environment, or pass it with -D. A launcher of ocx 0.6.5 or earlier exports OCX_FROZEN and OCX_INDEX, and the nested configure inherits them. -DOCX_FROZEN= and -DOCX_INDEX= opt out.
OCX_AUTH_<REGISTRY>_{TYPE,USER,TOKEN} credentials are never snapshotted into the cache. Export them in the environment, and reconfigure after changing them.