Use find_package with find_ocx

Use this page to find the ocx CLI the classic way with find_package(ocx), and to let a later find_package(<name>) search content that find_ocx provisioned.

Find the ocx CLI

Use find_package(ocx) when a system ocx should win over the pinned bootstrap. The module honors -DOCX_EXECUTABLE, searches PATH, and defines the ocx::ocx imported target.

examples/find_package/CMakeLists.txt

cmake_minimum_required(VERSION 3.15)
project(ocx_example_find_package LANGUAGES NONE)

enable_testing()

list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../..")
find_package(ocx REQUIRED)

message(STATUS "example: ocx ${OCX_VERSION_STRING} at ${OCX_EXECUTABLE}")

add_test(NAME ocx_version COMMAND ocx::ocx version)

Configure and test it. -DOCX_BOOTSTRAP=ON falls back to the pinned CLI when none is found.

cmake -S . -B build -DOCX_BOOTSTRAP=ON && ctest --test-dir build

The module needs CMake 3.15, or 3.19 with ocx.cmake next to Findocx.cmake when you use the bootstrap. To choose between this and include(ocx), see Two entry points.

Make find_package search a pulled package

Pull a package at configure time with PULL. find_ocx then sets <name>_ROOT to the package content root, following policy CMP0074. A later find_package(<name>) or find_library call searches that content.

examples/package/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}")

Add NO_ROOT to suppress the export. To pull every package at configure time, for example in CI, configure with -DOCX_PULL=ON.

The example opts out of the floating-tag check on purpose. In your project, freeze the tag first: see Pin and freeze tag resolution.

Needs addressed: problems 4 and 7 of the use-case research.