- integrations
- CMake
- Everyday
- Add or change a pinned tool
Add or change a pinned tool
A build needs one more command-line tool, say shellcheck, and every machine has a different copy or none.
A README line that says “install shellcheck first” drifts, and find_program takes whatever the host offers.
FetchContent and CPM fetch sources to compile, and vcpkg and Conan centre on libraries built with your toolchain.
Pinning one prebuilt tool for one build step is not what they are built for.
This page adds the tool to ocx.toml, refreshes ocx.lock and selects the tool in CMake, so a teammate who pulls the change gets the same copy.
You need a project that already calls ocx_project, as in the tutorial.
You also need an ocx CLI on the machine that writes the lock, or the CLI that find_ocx downloads, as the next section shows.
Machines that only build do not need one.
Add the tool to a group
Section titled “Add the tool to a group”Put a tool every target uses under [tools].
Put a tool that few targets use in its own group, here lint.
[tools]jq = "ocx.sh/jqlang/jq:latest"
[group.lint.tools]shellcheck = "ocx.sh/shellcheck/shellcheck:latest"The tools under [tools] form the group named default.
Refresh the lock and commit it
Section titled “Refresh the lock and commit it”Run ocx lock in the directory that holds ocx.toml.
The lock records the digest of every tool on every platform.
Commit ocx.toml and ocx.lock together.
If you skip this step, the next configure stops with exit code 65 and names the command to run. The recording shows that failure and the repair.
ocx lock also asks you to add one line to .gitattributes.
Add it, so two branches that each add a tool merge without a conflict in the lock.
ocx.lock merge=unionWrite the first lock without an installed ocx
Section titled “Write the first lock without an installed ocx”A configure checks the lock and never writes it.
A project with an ocx.toml and no ocx.lock therefore stops the first configure with exit code 78 and this message:
ocx.lock not found at <path>/ocx.lock; run `ocx lock` to create itOn a machine with no ocx, that stop comes after the configure has downloaded the pinned CLI, and OCX_EXECUTABLE in the cache names it.
Run that binary to write the lock, then configure again.
The recording runs the three commands on a machine with no ocx.
cmake -L -N build prints the cache entry OCX_EXECUTABLE, and the sed filter keeps its value.
The command substitution needs a POSIX shell.
On Windows, copy the path from the OCX_EXECUTABLE:FILEPATH= line and run <path> lock in the directory of ocx.toml.
The CLI that wrote the lock is the one the next configure runs, so both agree on the lock format.
A lock that a different ocx wrote can fail with exit code 78, as Fix a failing configure describes.
Select the group in CMake
Section titled “Select the group in CMake”ocx_project provisions the default group unless you name groups.
Name default next to each extra group, or the top-level tools leave the environment.
BINS lists the executables you want as variables, so the call below exports OCX_DEV_RUN_SHELLCHECK and OCX_DEV_RUN_JQ.
# A BINS entry from a non-default group needs that group in GROUPS, and# 'default' keeps the top-level [tools] in the same 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")Use the variable anywhere CMake takes a command list, as the test above does.
The command resolves shellcheck from the locked group, never from the host PATH.
A BINS name that the selected groups do not provide stops the configure.
The error names the entry and lists the names that are declared, so a typo or a forgotten group shows up at once.
To keep a group out of the default environment, give it its own ocx_project call when only one target needs it.
The group costs nothing until someone builds that target.
# The lint group only materializes when someone builds the 'lint' target.ocx_project(NAME LINT GROUPS lint)add_custom_target( lint COMMAND ${OCX_LINT_RUN} shellcheck "${CMAKE_CURRENT_SOURCE_DIR}/hello.sh" VERBATIM)Check that the pin runs
Section titled “Check that the pin runs”Configure, build and test the project.
The shellcheck_hello test passes on a machine whose PATH has no shellcheck, because the launcher puts the locked copy first.
A teammate gets the new tool by pulling and configuring, with no install step.
Leave .ocx/toolchain out of version control.
The first run creates .ocx/toolchain next to ocx.toml.
It holds links into the local store and carries its own .gitignore, so git skips it without a rule from you.
It is not the committed .ocx/ index snapshot of Pin and freeze tag resolution, which holds a <registry>/p/ directory instead.
Next steps
Section titled “Next steps”- Pin and freeze tag resolution freezes floating tags for
ocx_package. - Fix a failing configure maps an error to its cause.
ocx_projectlists every keyword.