Skip to content
ocx
install

Lazy versus eager

This page explains when a configure downloads package content, what PULL changes, and what a reconfigure costs. It helps you tell whether a configure touched the network, and how to force a refresh.

The exported OCX_<NAME>_RUN commands re-enter ocx exec or ocx package exec. Those launchers install missing content on first execution. So a configure downloads no package content, and the build downloads it when a target first runs the tool.

Call Content is downloaded Why
ocx_project On the first run of an OCX_<NAME>_RUN command The lock check is offline and the launcher installs the rest.
ocx_package On the first run of an OCX_<NAME>_RUN command The same launcher mechanism.
Either with PULL At configure ocx pull or ocx package install runs before the call returns.
Either with a foreign PLATFORM At configure The paths in OCX_<NAME>_PATHS must point at content that exists.

The bootstrap of the ocx binary is separate. It downloads once per machine and logs the download.

To find out whether a configure needs the network, configure a fresh build directory with -DOCX_OFFLINE=1. A call that needs content stops with exit 79 when the package is pinned and the store lacks it. A tag that a snapshot resolves stops with exit 81 when its manifest is not cached. The message names the command. A lazy call with a digest reference and BINS passes, and prints a status line instead of checking the names:

find_ocx: ocx_package X (<ref>): BINS not validated (OCX_OFFLINE and the package is not in the local store)

A configure that passes touched no network.

PULL on a call, or -DOCX_PULL=ON for every call, materializes content at configure time. On ocx_package, PULL also exports <name>_ROOT, so a later find_package or find_program can search the content. CI jobs often set OCX_PULL=ON, so a missing package fails the configure and warms the cache.

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}")

The OCX_ALLOW_FLOATING lines are there because this example resolves a floating tag live. With a lock file, an index snapshot or an image index digest, the ocx_package line stands alone. A lazy call pins the reference and waits for the first execution:

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

A lazy configure leaves the package store empty. A later offline run of the tool then fails with exit 79 for a pinned package, because nothing was downloaded while the network was reachable. The build step prints error: failed to find package: <ref> — package not found. A tag that a snapshot resolves fails with exit 81 instead.

Fill the store first, with a configure that pulls. Then configure offline against the lock file or snapshot:

cmake -S . -B build -DOCX_PULL=ON
cmake -S . -B build-offline -DOCX_OFFLINE=1 -DOCX_FROZEN=1

The second command reuses the filled store and refuses any network use. It uses a new build directory because OCX_OFFLINE and OCX_FROZEN are site variables, and a build directory keeps the value of its first configure.

Each provisioning call fingerprints its inputs. They are the module version, the ocx version and path, the contents of ocx.toml and ocx.lock, and the call’s arguments. When the fingerprint matches and the store paths still exist, no ocx process starts. The log says up to date (memoized) instead, and the module’s own test asserts that line on the second configure:

reconfigure_check.cmake
assert_memo(repeat "${out}" TRUE ${untouched} ${touched})

A change to any input, or a store that lost the content, runs ocx again. -DOCX_REFRESH=ON bypasses the memo once and then clears itself.