Install your first package

By the end of this page you have run CMake without installing it, installed two versions side by side, switched between them and removed both. It assumes ocx is installed. Package names such as kitware/cmake resolve against the default registry, ocx.sh.

Run a package once

Run CMake straight from the registry. The first call downloads the package. Later calls with the same version reuse the download.

ocx package exec kitware/cmake:3.31 -- cmake --version

cmake version 3.31.12

CMake suite maintained and supported by Kitware (kitware.com/cmake).

The command ran inside an isolated environment that holds only the variables the package declares. Nothing else persists on your machine: no install, no symlink. The patch number you see depends on the current 3.31 release.

Install it

Make the download permanent and give it a stable path. The paths on this page assume the default home directory, ~/.ocx:

ocx package install kitware/cmake:3.31

Package             Version                    Path
kitware/cmake:3.31  ocx.sh/kitware/cmake:3.31  ~/.ocx/symlinks/ocx.sh/kitware/cmake/candidates/3.31

The Path column is a candidate symlink. It always points at the 3.31 build you installed, so an editor or script can use it as a fixed path.

Switch versions

Install a second version and mark it as the one you use. The --select flag creates a current symlink next to the candidates:

ocx package install --select kitware/cmake:4.0

Package            Version                   Path
kitware/cmake:4.0  ocx.sh/kitware/cmake:4.0  ~/.ocx/symlinks/ocx.sh/kitware/cmake/current

Run the binary through current. The path has no version in it:

~/.ocx/symlinks/ocx.sh/kitware/cmake/current/content/bin/cmake --version

cmake version 4.0.7

Point current back at 3.31, then run the same path again:

ocx package select kitware/cmake:3.31

~/.ocx/symlinks/ocx.sh/kitware/cmake/current/content/bin/cmake --version

cmake version 3.31.12

The path stayed the same and the version behind it changed. Installing with --select does not put a bare cmake on your PATH. The next steps show how to get that.

See the environment

A package can declare environment variables, such as the PATH entry for its bin directory. List what the installed package declares:

ocx package env kitware/cmake:3.31

The output is a table with the columns Key, Type and Value. Each value is resolved against the install location. ocx package exec injects exactly these variables into the child process.

Remove the packages

Remove the selected version, clear the current pointer and delete the package data in one command:

ocx package uninstall --deselect --purge kitware/cmake:3.31

Package             Status
kitware/cmake:3.31  removed
kitware/cmake:3.31  purged

A plain uninstall removes the candidate symlink and keeps the package data. Uninstall 4.0 that way, then let ocx clean delete every package nothing references anymore:

ocx package uninstall kitware/cmake:4.0
ocx clean

The last command prints one line for each object it deletes. Both versions are gone.

Next steps

• Pin the tools of one repository in your first project.
• Put a tool on your PATH in every shell with the global toolchain, or let shell integration do it per project.
• Learn how version tags work, so you know why 3.31 and 4.0 pick the builds they do.
• Look up flags in the ocx package reference and the environment reference.

A tag that does not exist in the registry fails with exit code 79. On a fresh install the local index is empty, so index commands need --remote until a package is installed. List the tags a repository publishes with ocx --remote index list kitware/cmake. Global flags such as --remote go before the subcommand.