- integrations
- CMake
- Concepts
- Lazy versus eager
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.
Lazy by default
Section titled “Lazy by default”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.
Eager mode
Section titled “Eager mode”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.
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:
ocx_package( NAME jq_pinned PACKAGE ocx.sh/jqlang/jq:1.8.2@sha256:c295300441831e002c0ba54df8e6126cdd4064c63be2464bdc6b68d0012beec6 BINS jq NO_ROOT)Preparing an offline build
Section titled “Preparing an offline build”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=ONcmake -S . -B build-offline -DOCX_OFFLINE=1 -DOCX_FROZEN=1The 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.
Reconfigures are memoized
Section titled “Reconfigures are memoized”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:
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.
Related pages
Section titled “Related pages”- Reproduce the build in CI switches a CI job to eager mode.
- Reproducible first explains the frozen configure.
- Environment and config explains why a build directory keeps its first value.