- integrations
- CMake
- Everyday
- Make the build find provisioned content
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.
Pull the package and export its root
Section titled “Pull the package and export its root”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.
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.
Search with find_package or find_library
Section titled “Search with find_package or find_library”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.
Locate a program in the content
Section titled “Locate a program in the content”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.
# 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 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.
Next steps
Section titled “Next steps”- Pin and freeze tag resolution fixes what the tag means.
- Use an ocx you already installed covers
find_package(ocx). ocx_packagelists every keyword.