Examples

All examples live in examples/ and are built and tested on Linux, macOS and Windows in CI. The sources below are included verbatim from the repository.

Workspace toolchain (ocx_project)

A committed ocx.toml + ocx.lock pair describes the toolchain; CMake turns it into launcher variables. Tools materialize lazily on first execution, and groups only when a target that uses them is built.

examples/project/ocx.toml

[tools]
jq = "ocx.sh/jqlang/jq:latest"

[group.lint.tools]
shellcheck = "ocx.sh/shellcheck/shellcheck:latest"

examples/project/CMakeLists.txt

cmake_minimum_required(VERSION 3.19)
project(ocx_example_project LANGUAGES NONE)

enable_testing()

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

# The ocx.toml next to this file is found by the upward search; the lock
# is verified; nothing is pulled yet (lazy). NAME picks the prefix of the
# result variables: NAME TOOLS -> OCX_TOOLS_RUN, OCX_TOOLS_RUN_JQ
# (defaults to PROJECT -> OCX_PROJECT_RUN).
ocx_project(NAME TOOLS BINS jq)

# Build-time tool use, lazily materialized on first execution. Generator
# expressions compose naturally - the command is a plain CMake list.
add_custom_target(validate ALL
  COMMAND ${OCX_TOOLS_RUN} jq -n -e --arg config "$<CONFIG>"
          [[$config | length >= 0]]
  VERBATIM
)

# The lint group only materializes when someone builds the 'lint' target.
ocx_project(NAME LINT GROUPS lint)
add_custom_target(lint
  COMMAND ${OCX_LINT_RUN} shellcheck "${CMAKE_CURRENT_SOURCE_DIR}/hello.sh"
  VERBATIM
)

add_test(NAME data_valid
  COMMAND ${OCX_TOOLS_RUN_JQ} -e ".greeting == \"hello\""
          "${CMAKE_CURRENT_SOURCE_DIR}/data.json")

Highlights:

• The ocx.toml is found by the upward search, the lock is verified, nothing is fetched yet.
• NAME picks the result-variable prefix: NAME TOOLS → OCX_TOOLS_RUN / OCX_TOOLS_RUN_JQ (NAME defaults to PROJECT).
• OCX_<NAME>_RUN is a plain CMake command list — generator expressions like $<CONFIG> compose naturally, no wrapper scripts.
• The lint group costs nothing until someone builds the lint target.

The ad-hoc package and discovery examples cover ocx_package, the project-shipped index snapshot and classic find_package.

Running them

cd examples/project        # or examples/package
cmake -S . -B build
cmake --build build
ctest --test-dir build --output-on-failure

For CI, add -DOCX_PULL=ON to materialize everything at configure time.