Skip to content
ocx
install

Make the build find provisioned content

Your build needs a library or a tool that CMake locates with find_package, find_library or find_program. Left alone, those commands return whatever the host has, so two machines build against two different copies and the log looks fine on both. A README line that says “install it first” does not change that. This page pulls the package at configure time and points the search at the provisioned content.

The example accepts a floating tag to stay short. In your project, freeze the tag first with Pin and freeze tag resolution.

Add PULL to the ocx_package call. find_ocx installs the package during configure and sets <name>_ROOT to the content root, following policy CMP0074.

CMakeLists.txt
set(OCX_ALLOW_FLOATING ON)
ocx_package(NAME jq PACKAGE ocx.sh/jqlang/jq:latest PULL)
unset(OCX_ALLOW_FLOATING)
message(STATUS "example: jq content at ${jq_ROOT}")

The variable keeps the case of NAME, so this call sets jq_ROOT. Add NO_ROOT to suppress the export. To pull every package at configure time, for example in CI, configure with -DOCX_PULL=ON.

find_package(<name>) and the find_* calls inside find modules read <name>_ROOT. They search the provisioned content first when the package ships a find module or a config file.

When the root changes, find_ocx also clears the cached <name>_DIR. Without that, find_package would keep answering with the copy it found before.

A package that ships only a program has nothing for find_package to read. find_package(jq) reports that jq is not found, even though the content is there. Use find_program for such a package.

A top-level find_program ignores <name>_ROOT, so a plain find_program(JQ_EXE jq) returns the host jq when one exists. Name the content root as a hint and turn off the default search paths.

CMakeLists.txt
# find_program() ignores <name>_ROOT - only find_package() reads it - so hand
# the content root over as HINTS. NO_DEFAULT_PATH keeps a host jq from
# answering; NO_CACHE re-searches when jq_ROOT moves to another digest.
find_program(JQ_EXECUTABLE NAMES jq HINTS "${jq_ROOT}" "${jq_ROOT}/bin" NO_DEFAULT_PATH NO_CACHE)
if(NOT JQ_EXECUTABLE)
message(FATAL_ERROR "example: no jq under ${jq_ROOT}")
endif()
message(STATUS "example: find_program found ${JQ_EXECUTABLE}")

Where the program sits depends on the package. For jq it is the content root, and many packages use a bin directory, so the call lists both. The recording provisions lychee, which the host does not have. The plain call therefore returns NOTFOUND, and the call with HINTS "${lychee_ROOT}" returns the file under the package root. On a machine that has the tool, the plain call would return the host copy instead.

find_program does not search the package root

find_program stores its answer in the CMake cache. After you change the pin, delete the entry with -UJQ_EXE or use a fresh build directory.

If you only need to run the tool, skip the search. The OCX_<NAME>_RUN command list from ocx_package runs it from the pin, as Add or change a pinned tool shows.