Skip to content
ocx
install

Reproduce the build in CI

A build passes on your laptop and fails on a CI runner because the two machines carry different tool versions. A README line such as “install jq 1.7 first” cannot prevent that, and FetchContent or CPM fetch sources to compile, not a pinned jq for a custom command.

This page sets up a CI job that runs the same ocx and the same locked tools on Linux, macOS and Windows. The job fails at configure time when a tool is missing or the lock is stale. It assumes a project that already calls ocx_project or ocx_package, as in the tutorial.

By default find_ocx uses an ocx found on PATH and downloads its pinned one only when there is none. A runner image can therefore carry a different ocx than your laptop.

Configure with -DOCX_BOOTSTRAP=ALWAYS. The PATH search is skipped, so every runner downloads and runs the identical sha256-verified binary. Add -DOCX_INSTALL_VERSION=<version> to choose a version other than the one pinned by your find_ocx release.

The tool versions come from ocx.lock, not from the CLI. ocx.lock stores one digest per tool and platform, so all three runners pull the same bytes.

Add -DOCX_PULL=ON. Every ocx_project and ocx_package call then installs its content while CMake configures, instead of when a build step first runs the tool. A package that does not resolve fails the Configure step, and the cache holds the content before the build starts.

ocx_project also runs ocx lock --check on every configure. When ocx.toml changed and ocx.lock did not, the job fails with exit code 65 and the instruction to run ocx lock and commit the result. The exit codes page lists every code the module reports.

find_ocx writes to two places.

  • The ocx store, which holds installed packages. It is ~/.ocx unless OCX_HOME names another directory.
  • The bootstrap cache, which holds the downloaded ocx. It is per machine unless OCX_BOOTSTRAP_CACHE names another directory.

Home directories on hosted runners are not always writable or stable. Point both variables into the workspace and restore that directory with your CI cache, keyed on ocx.lock. A changed lock then produces a fresh cache, and an unchanged one skips every download.

Configure a second, empty build directory with OCX_OFFLINE=1 and -DOCX_PULL=ON after the first configure. It succeeds only if the store holds everything the build needs, so a hidden download shows up as a failed job.

This GitHub Actions workflow applies all four settings on three operating systems.

github-actions.yml
name: Build
on: [push, pull_request]
permissions:
contents: read
jobs:
build:
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
env:
OCX_HOME: ${{ github.workspace }}/.cache/ocx-home
OCX_BOOTSTRAP_CACHE: ${{ github.workspace }}/.cache/ocx-bootstrap
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
persist-credentials: false
- uses: actions/cache@v4.3.0
with:
path: .cache
key: ocx-${{ runner.os }}-${{ hashFiles('ocx.lock') }}
- name: Configure
shell: bash
run: cmake -Werror=dev -S . -B build -DCMAKE_BUILD_TYPE=Release -DOCX_BOOTSTRAP=ALWAYS -DOCX_PULL=ON
- name: Build and test
shell: bash
run: |
cmake --build build --config Release
ctest --test-dir build -C Release --output-on-failure --no-tests=error --timeout 300
- name: Configure again, offline
shell: bash
env:
OCX_OFFLINE: "1"
run: cmake -Werror=dev -S . -B build/offline -DOCX_BOOTSTRAP=ALWAYS -DOCX_PULL=ON

The workflow pins checkout to a commit SHA, because a tag can move. The job token is read-only and checkout does not persist it. The configure fails on a CMake author warning. The test run fails when it finds no tests. A hung test is cut off after 300 seconds.

find_ocx’s own lint step checks the file with actionlint. The same flags work in any CI system, because they are plain CMake and environment settings.

A leg that cannot reach the registry exits with code 69 or 75. ocx.cmake retries a temporary failure (75) twice on the calls that download, then gives up. Exit codes lists them.

For every variable on this page, see the variable reference.