- integrations
- CMake
- Everyday
- Use an ocx you already installed
Use an ocx you already installed
Your developers and runners already have the ocx CLI, installed by your package manager or an image.
You want builds to use that copy and to know which one ran, not to download a second ocx on every fresh checkout.
This page makes a configure use the installed CLI, shows how to tell which binary it picked, and covers the classic find_package(ocx) entry point.
You need ocx installed on each machine.
The installation page lists the ways.
Let the module pick up the CLI on PATH
Section titled “Let the module pick up the CLI on PATH”Do nothing.
The first ocx_project or ocx_package call looks for the CLI in this order:
OCX_EXECUTABLE, when you set it.- An
ocxonPATH. - A pinned CLI that find_ocx downloads into a per-machine cache.
Machines that have ocx stop at step 2 and download nothing.
Tell which binary a configure runs
Section titled “Tell which binary a configure runs”Every configure names a choice the module made itself in one status line.
It reads find_ocx: using ocx from PATH (<path>) - OCX_BOOTSTRAP=ALWAYS forces the pinned bootstrap instead, or find_ocx: using bootstrapped ocx <version> (<path>) when the pin was downloaded.
The module chooses again on each configure, so a changed ocx on PATH is picked up.
An explicit OCX_EXECUTABLE is kept as given and prints nothing.
The cache holds the answer for reading, and cmake -LA -N build prints it as OCX_EXECUTABLE.
To read that binary’s version, run ocx version, because the CLI has no --version flag.
Name the binary yourself
Section titled “Name the binary yourself”Set OCX_EXECUTABLE when several copies exist and one must win.
Pass -DOCX_EXECUTABLE=/opt/ocx/bin/ocx, or export the variable and the first configure stores it.
Find the CLI with find_package
Section titled “Find the CLI with find_package”Use find_package(ocx) when your own CMake code runs ocx, for example in a custom command.
It honours OCX_EXECUTABLE, searches PATH, and defines the imported target ocx::ocx.
Point CMAKE_MODULE_PATH at the directory with your vendored Findocx.cmake, as the first line of the example does for this repository.
list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../..")find_package(ocx REQUIRED)
message(STATUS "example: ocx ${OCX_VERSION_STRING} at ${OCX_EXECUTABLE}")Unlike include(ocx), the find module does not download anything by default.
Add -DOCX_BOOTSTRAP=ON to fall back to the pinned CLI when none is found.
The recording configures the example and prints the version it found.
Two entry points compares the two ways to start.
Forbid the download
Section titled “Forbid the download”Pass -DOCX_BOOTSTRAP=OFF on machines where configure must never download.
A missing CLI then stops the configure with this message:
find_ocx: no ocx on PATH, OCX_EXECUTABLE is not set, and implicit bootstrap is disabled (OCX_BOOTSTRAP=OFF)hint: install ocx on PATH or set OCX_EXECUTABLE to an ocx binaryAn empty value, as in -DOCX_BOOTSTRAP=, counts as unset, so the default ON applies and a missing CLI is downloaded.
OFF is the only value that forbids the download.
ON, OFF and ALWAYS are the accepted values, in any case, and the module rejects every other one.
Run the pinned CLI everywhere
Section titled “Run the pinned CLI everywhere”Pass -DOCX_BOOTSTRAP=ALWAYS to skip the PATH search.
Every machine then runs the identical pinned binary, which removes version differences between installs.
Use it when installed copies are old or unmanaged.
Keep the installed CLI current
Section titled “Keep the installed CLI current”find_ocx is tested against its pinned CLI version 0.6.6, which OCX_INSTALL_VERSION defaults to.
An ocx below 0.6.0 lacks verbs the module calls, and the configure then fails with exit code 64 and its hint.
Versions from 0.6.0 up to 0.6.5 are untested, though the module reads their report shapes too.
An ocx above 0.6.6 is expected to work until ocx removes a verb the module calls.
When in doubt, use ALWAYS.
Next steps
Section titled “Next steps”- Build behind a mirror or offline covers machines that cannot reach the download host.
- Reproduce the build in CI pins one CLI for every runner.
ocx_bootstraplists the bootstrap keywords.