Skip to content
ocx
install

ocx_project

Provisions the toolchain of a workspace ocx.toml and its ocx.lock.

ocx_project([NAME <name>] [TOML <ocx.toml>] [LOCK <ocx.lock>]
[GROUPS <group>...] [BINS <tool>...]
[PLATFORM <ocx-platform>] [PULL]
[CONFIG <config.toml>] [NO_CONFIG] [PATCH_SNAPSHOT <path>])

The call always runs ocx lock --check, an offline staleness gate for the lock file. Content materializes on first execution. PULL or OCX_PULL materializes it at configure time instead.

Calling the command again with the same NAME and identical arguments does nothing, because CMake includes a toolchain file twice. The same NAME with different arguments is an error.

Changed in version 0.4. An empty argument value is an error, because it usually means that a variable is unset.

NAME <name>

Prefix of the result variables. The default is PROJECT. The module upper-cases the name and reduces it to a C identifier.

TOML <ocx.toml>

The workspace declaration. The default is OCX_PROJECT_FILE, else the nearest ocx.toml between the calling directory and the last project() source directory. In script mode the search walks to the filesystem root.

LOCK <ocx.lock>

The lock file. The default is the ocx.lock next to the declaration.

GROUPS <group>...

Groups that the commands see. The [tools] table is the group default, which a GROUPS list must name itself.

BINS <tool>...

Tools that get an OCX_<NAME>_RUN_<BIN> command. Entries are executable names on the composed environment, not package references, because a package may ship several tools. A name that no locked package declares is a configure error that lists the declared names. A name that only a group outside GROUPS declares says so. The check is skipped while OCX_OFFLINE is set and the packages are not in the local store.

BINS is an error together with PLATFORM, because content for another platform cannot run on the host.

Changed in version 0.4. The module checks every name against the binaries and entrypoints that ocx inspect --closure reports.

PLATFORM <ocx-platform>

One ocx platform such as linux/arm64. The default is OCX_DEFAULT_PLATFORM, else the host. The call pulls that platform’s content from the same ocx.lock. It exports the platform result variables instead of the command lists. A list of platforms is an error, so call the command once per platform under its own NAME.

PULL

Materialize the content at configure time. OCX_PULL does the same for every call. PLATFORM always pulls.

CONFIG <config.toml>

An ocx config file that applies as OCX_CONFIG to every ocx call of this command and to the exported OCX_<NAME>_RUN. A relative path resolves against the calling directory.

NO_CONFIG

Skip the user, $OCX_HOME and managed config tiers, as OCX_NO_CONFIG=1 does.

PATCH_SNAPSHOT <path>

A patch snapshot that applies as OCX_PATCH_SNAPSHOT.

Each of the three config keywords overrides the environment variable of the same name for this command.

New in version 0.4. CONFIG, NO_CONFIG and PATCH_SNAPSHOT.

The call exports these variables as global cache-internal values, usable from any directory. Each run removes the variables of the same NAME that an earlier configure exported. A dropped BINS entry therefore leaves no command behind.

OCX_<NAME>_RUN

Command-list prefix that composes the project environment and runs any tool on it.

Changed in version 0.4. The prefix calls ocx exec.

OCX_<NAME>_RUN_<BIN>

Per-tool command for every name in BINS. <BIN> is the upper-cased executable name.

OCX_<NAME>_PATHS, OCX_<NAME>_ENV_<KEY>, OCX_<NAME>_ENV_KEYS

Set with PLATFORM instead of the command lists. They hold the PATH directories (digest paths, in environment order), the constant environment values and the list of their <KEY> names.

The tested project examples/project builds a tool command and a test from the lazy OCX_TOOLS_RUN prefix.

include(ocx)
ocx_project(NAME TOOLS BINS jq)
add_test(
NAME data_valid
COMMAND ${OCX_TOOLS_RUN_JQ} -e ".greeting == \"hello\"" "${CMAKE_CURRENT_SOURCE_DIR}/data.json"
)

The same project selects groups. A BINS entry from a non-default group needs that group in GROUPS, and default keeps the top-level [tools] table in the environment.

ocx_project(NAME DEV GROUPS default lint BINS jq shellcheck)
add_test(
NAME shellcheck_hello
COMMAND ${OCX_DEV_RUN_SHELLCHECK} "${CMAKE_CURRENT_SOURCE_DIR}/hello.sh"
)

The tested project examples/cross_build provisions the linux/arm64 content from a toolchain file.

ocx_project(NAME TARGET TOML "${CMAKE_CURRENT_LIST_DIR}/ocx.toml" PLATFORM linux/arm64)
list(APPEND CMAKE_FIND_ROOT_PATH ${OCX_TARGET_PATHS})

The tested project examples/policy pins one ocx config file and ignores the config files of the machine.

ocx_project(NAME TOOLS BINS jq CONFIG "${CMAKE_CURRENT_SOURCE_DIR}/ocx-config.toml" NO_CONFIG)

All commands are listed in the command reference.