Skip to content
ocx
install

ocx_package

Provisions a single OCX package from an OCI registry.

ocx_package(NAME <name> PACKAGE <registry/repo[:tag][@sha256:...]>
[INDEX <dir> | NO_INDEX] [BINS <tool>...]
[PLATFORM <ocx-platform>] [PULL] [NO_ROOT]
[CONFIG <config.toml>] [NO_CONFIG] [PATCH_SNAPSHOT <path>])

The call exports the same OCX_<NAME>_RUN and OCX_<NAME>_RUN_<BIN> command lists as ocx_project. The lists re-enter ocx package exec and are lazy by default. PULL or OCX_PULL installs the package at configure time instead. A floating tag needs an index snapshot or an image index digest, as Tag resolution describes.

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.

Changed in version 0.4. PINS is removed. Pin a floating tag with a committed index snapshot, or with the image index digest in PACKAGE.

NAME <name>

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

PACKAGE <registry/repo[:tag][@sha256:...]>

The package reference. The option is required. A @sha256: digest pins the package. An image index digest pins every platform at once, and ocx selects the leaf for the effective platform, features included. ocx package inspect <registry/repo:tag> prints it as pinned_digest.

INDEX <dir>

Index snapshot directory that freezes tag resolution for this package.

NO_INDEX

Skip index resolution. INDEX and NO_INDEX exclude each other.

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. The module checks every name against the binaries and entrypoints that ocx package inspect --closure reports. A typo is a configure error that lists the declared names.

Lazy and eager provisioning both run the check. The check is skipped while OCX_OFFLINE is set and the package is 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 validates BINS.

PLATFORM <ocx-platform>

One ocx platform. The default is OCX_DEFAULT_PLATFORM, else the host. The call installs the package eagerly and 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

Install the package at configure time. PLATFORM always installs.

NO_ROOT

Do not export <name>_ROOT.

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.

Tag resolution is frozen against the first index snapshot in effect. The candidates, in order, are:

  1. The explicit INDEX <dir>.
  2. The OCX_INDEX variable.
  3. The nearest committed .ocx/ directory between the calling directory and the last project() source directory.

A .ocx/ counts only when it holds a config.json or a <registry>/p/ directory. The .ocx/toolchain that ocx pull renders does not count. NO_INDEX skips all three.

A floating tag with no index in effect and no digest pin is a configure error unless OCX_ALLOW_FLOATING is set. Create and refresh a snapshot deliberately with ocx --index <dir> index update <package>. ocx_index composes the refresh command.

With an index in effect, the exported launchers run ocx --index <dir> --frozen and export both settings into child processes. A find_ocx configure nested under such a launcher inherits the outer resolution mode. Pass -DOCX_FROZEN= and -DOCX_INDEX= to opt out.

The call exports these variables as global cache-internal values. Each run of a changed call removes the variables of the same NAME that an earlier configure exported, <name>_ROOT included.

OCX_<NAME>_RUN, OCX_<NAME>_RUN_<BIN>

The command lists described for ocx_project.

OCX_<NAME>_CONTENT

The package content directory. The call sets it when it installs the package.

<name>_ROOT

The same directory under the original-case name (CMP0074). A following find_package(<name>) or find_library searches the OCX-provisioned content. find_program ignores the variable, so pass HINTS ${<name>_ROOT}. NO_ROOT suppresses it.

Changed in version 0.4. A changed value also unsets <name>_DIR, so find_package stops answering with the old copy.

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

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

The tested project examples/package pins the image index digest and keeps the package lazy.

ocx_package(
NAME jq_pinned
PACKAGE ocx.sh/jqlang/jq:1.8.2@sha256:c295300441831e002c0ba54df8e6126cdd4064c63be2464bdc6b68d0012beec6
BINS jq
NO_ROOT
)

The same project resolves a floating tag from a snapshot directory, with no digest in the CMake code.

ocx_package(
NAME jq_frozen
PACKAGE ocx.sh/jqlang/jq:latest
BINS jq
NO_ROOT
INDEX "${CMAKE_CURRENT_SOURCE_DIR}/index"
)

The same project installs a floating tag eagerly and hands the content root to find_program. OCX_ALLOW_FLOATING is the deliberate escape hatch here, and the log says how to pin the tag.

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}")
find_program(JQ_EXECUTABLE NAMES jq HINTS "${jq_ROOT}" "${jq_ROOT}/bin" NO_DEFAULT_PATH NO_CACHE)

All commands are listed in the command reference.