- integrations
- CMake
- Reference
- Commands
Commands
Reference for the six commands that ocx.cmake defines.
This page is generated from the module source, and each command has a page of its own.
Overview
Section titled “Overview”CMake support for OCX, the OCI-backed package manager. The module installs a pinned ocx CLI and provisions tools through it. It never re-implements OCX internals in CMake. All resolution goes through the ocx binary, so the durable contracts are the ocx.lock digests and the OCI manifests.
Vendor ocx.cmake together with Findocx.cmake into your project, for example into cmake/. Include the module after project().
Changed in version 0.4. The module requires CMake 3.25 or later. Release 0.3 accepted CMake 3.19.
cmake_minimum_required(VERSION 3.25...4.4)project(hello_jq LANGUAGES NONE)
list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")include(ocx)
ocx_project(NAME TOOLS BINS jq)
add_custom_target(show_jq ALL COMMAND ${OCX_TOOLS_RUN} jq --version VERBATIM)The project is examples/tutorial/CMakeLists.txt, built by the tutorial/first-configure cast test.
Synopsis
Section titled “Synopsis”Install the CLI ocx_bootstrap([VERSION <version>] [TRIPLE <target-triple>] [DIST_MANIFEST <dist.json>]) ocx_self_update()
Provision tools ocx_project([NAME <name>] [TOML <ocx.toml>] [LOCK <ocx.lock>] [GROUPS <group>...] [BINS <tool>...] [...]) ocx_package(NAME <name> PACKAGE <package> [BINS <tool>...] [...])
Freeze tag resolution ocx_index(FIND [REQUIRED]) ocx_index(UPDATE_COMMAND <out-var> [INDEX <dir>] [PACKAGES <ref>...])
Set the verification policy ocx_policy([ALLOW_UNVERIFIED] [ALLOW_YANKED] [SIGSTORE_TRUSTED_ROOT <file>])Find the CLI
Section titled “Find the CLI”include(ocx) is passive. It only defines the commands and snapshots the OCX_* variables from the environment. The first provisioning call resolves the CLI. That call is ocx_project, ocx_package or an explicit ocx_bootstrap.
The module takes OCX_EXECUTABLE when it is set, else an ocx on PATH, else the pinned CLI. It downloads the pinned CLI, verified by sha256, into the per-machine cache.
OCX_BOOTSTRAP changes this order. ALWAYS skips the PATH search, so every machine runs the identical pinned binary. OFF forbids the implicit download. An explicit ocx_bootstrap call always provisions the pin.
Reproducible resolution
Section titled “Reproducible resolution”Resolution is reproducible first. A floating tag resolves through a committed index snapshot or through digest pins. The snapshot is the nearest .ocx/ directory, discovered the way ocx.toml is. Create it with ocx --index .ocx index update <package>. With neither a snapshot nor a pin, the configure fails.
OCX_ALLOW_FLOATING is the explicit escape hatch. ocx_index finds and refreshes a snapshot.
Trust and mirrors
Section titled “Trust and mirrors”The sha256 column of the dist.json snapshot embedded in ocx.cmake makes a downloaded ocx CLI trustworthy. The module checks every archive against its row before extraction, whichever URL served the bytes. The script scripts/update_dist.py only ever adds rows to the embedded snapshot.
OCX_INSTALL_DIST_URL and the DIST_MANIFEST keyword of ocx_bootstrap replace the snapshot. The sha256 column of that manifest is then the trust root, trusted as far as its transport. A manifest file named <sha256>.json is the exception. Its name carries its own digest, and the fetch is verified against it.
The SHA256SUMS file of a find_ocx release is the trust root of ocx_self_update. The GitHub releases API only names the latest tag. Every download verifies TLS and is bounded by a timeout.
Anonymous read
Section titled “Anonymous read”The variables OCX_INSTALL_DIST_URL, OCX_INSTALL_MIRROR_URL and OCX_SELF_UPDATE_URL name hosts that find_ocx reads without credentials. A mirror must therefore allow anonymous read. A mirror locked down later fails the download, and the failure looks like a network error.
Commands
Section titled “Commands”ocx_policy: Weakens the verification posture of every later ocx call in this configure, explicitly.ocx_bootstrap: Downloads a pinned ocx CLI release for the host and setsOCX_EXECUTABLE.ocx_project: Provisions the toolchain of a workspaceocx.tomland itsocx.lock.ocx_package: Provisions a single OCX package from an OCI registry.ocx_index: Operates on committed index snapshots, the reproducibility mechanism for floating tags next to@sha256:image index digests.ocx_self_update: Replaces the vendoredocx.cmakeand a siblingFindocx.cmakewith a released find_ocx version.