- integrations
- CMake
- Get started
- Run jq in a CMake build without installing it
Run jq in a CMake build without installing it
In this tutorial you add find_ocx to an empty CMake project and run jq from a build target.
The build prints the jq version it ran.
You never install jq, and anyone who clones the project gets the same version.
You need CMake 3.25 or later and network access to the OCX registry or a mirror.
You also need an ocx CLI of version 0.6 or later (install it), once, to write the lock.
Without one, write the lock with the CLI that find_ocx downloads and then continue here.
Vendor the two files
Section titled “Vendor the two files”Download Findocx.cmake and ocx.cmake from the release assets.
Put both in a cmake/ directory of an empty project.
Run ls cmake.
It lists Findocx.cmake and ocx.cmake.
Copying these files into your repository is the whole installation.
Pin the tool
Section titled “Pin the tool”Create ocx.toml in the project root, next to the CMakeLists.txt you write in the next step.
It names the tools your build runs.
[tools]jq = "ocx.sh/jqlang/jq:latest"The tag latest is a moving target.
The lock step below freezes it to exact digests.
Declare the project
Section titled “Declare the project”Create CMakeLists.txt.
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 include(ocx) line is passive, so it defines commands and fetches nothing.
The ocx_project command reads ocx.toml and ocx.lock, and it exports OCX_TOOLS_RUN.
That variable is a plain CMake command list that runs a tool from the pinned toolchain.
The show_jq target uses it to run jq --version on every build.
Lock, configure and build
Section titled “Lock, configure and build”Run three commands.
The first writes ocx.lock, and the second configures the project.
The third builds it, which runs jq.
ocx lock
cmake -S . -B build
cmake --build buildThe lock step prints a table with the digest of the jq build for your platform.
The build ends with a line like jq-1.8.2.
Your paths, digests and timings differ from the recording.
That jq was fetched into the OCX store on first use and never reached your PATH.
The lock file fixes its version, so a rebuild on any machine prints the same line.
Run the configure command again.
With unchanged inputs find_ocx prints find_ocx: TOOLS up to date (memoized) and does not resolve or pull again.
ocx lock also warns about merge conflicts in your lock file.
Add the line ocx.lock merge=union to a .gitattributes file, so branches that both change the lock merge cleanly.
What you built
Section titled “What you built”You have a CMake project that runs a tool nobody installed, at a version the lock file fixes.
Commit ocx.toml, ocx.lock and the cmake/ directory.
A teammate or a CI runner then builds with nothing installed beyond CMake.
Next steps
Section titled “Next steps”- Add or change a pinned tool to run more tools and keep rarely used ones in groups.
- Pin and freeze tag resolution to make
ocx_packagereproducible without a project file. - Read how find_ocx works for what ran under the hood.
- Fix a failing configure when a step above does not end as described.