Setup-free CMake dependency management

CPM.cmake is a cross-platform CMake script that adds dependency management capabilities to CMake. It's built as a thin wrapper around CMake's FetchContent module that adds version control, caching, a simple API and more.

Manage everything

Any downloadable project or resource can be added as a version-controlled dependency through CPM, it is not necessary to modify or package anything. Projects using modern CMake are automatically configured and their targets can be used immediately. For everything else, the targets can be created manually after the dependency has been downloaded (see the snippets below for examples).

Further reading

• CPM: An Awesome Dependency Manager for C++ with CMake
• CMake and the Future of C++ Package Management

Full CMakeLists Example

cmake_minimum_required(VERSION 3.14 FATAL_ERROR)

# create project
project(MyProject)

# add executable
add_executable(main main.cpp)

# add dependencies
include(cmake/CPM.cmake)

CPMAddPackage("gh:fmtlib/fmt#7.1.3")
CPMAddPackage("gh:nlohmann/json@3.10.5")
CPMAddPackage("gh:catchorg/Catch2@3.4.0")

# link dependencies
target_link_libraries(main fmt::fmt nlohmann_json::nlohmann_json Catch2::Catch2WithMain)

See the examples directory for complete examples with source code and check below or in the wiki for example snippets.

Adding CPM

To add CPM to your current project, simply add the latest release of CPM.cmake or get_cpm.cmake to your project's cmake directory. The command below will perform this automatically.

mkdir -p cmake
wget -O cmake/CPM.cmake https://github.com/cpm-cmake/CPM.cmake/releases/latest/download/get_cpm.cmake

Or using PowerShell:

New-Item -ItemType Directory -Force -Path "cmake"
Invoke-WebRequest -Uri "https://github.com/cpm-cmake/CPM.cmake/releases/latest/download/get_cpm.cmake" -OutFile "cmake/CPM.cmake"

You can also download CPM.cmake directly from your project's CMakeLists.txt. See the wiki for more details.

Usage

After CPM.cmake has been added to your project, the function CPMAddPackage can be used to fetch and configure a dependency. Afterwards, any targets defined in the dependency can be used directly. CPMAddPackage takes the following named parameters.

CPMAddPackage(
  NAME          # The unique name of the dependency (should be the exported target's name)
  VERSION       # The minimum version of the dependency (optional, defaults to 0)
  PATCHES       # Patch files to be applied sequentially using patch and PATCH_OPTIONS (optional)
  OPTIONS       # Configuration options passed to the dependency (optional)
  DOWNLOAD_ONLY # If set to YES, the project is downloaded, but not configured (optional, default NO)
  [...]         # Origin parameters forwarded to FetchContent_Declare, see below
)

The origin may be specified by a GIT_REPOSITORY, but other sources, such as direct URLs, are also supported. If GIT_TAG hasn't been explicitly specified it defaults to v(VERSION), a common convention for git projects. On the other hand, if VERSION hasn't been explicitly specified, CPM can automatically identify the version from the git tag in some common cases. GIT_TAG can also be set to a specific commit or a branch name such as master, however this isn't recommended, as such packages will only be updated when the cache is cleared.

PATCHES takes a list of patch files to apply sequentially. For a basic example, see Highway. We recommend that if you use PATCHES, you also set CPM_SOURCE_CACHE. See issue 577.

If an additional optional parameter EXCLUDE_FROM_ALL is set to a truthy value, then any targets defined inside the dependency won't be built by default. See the CMake docs for details.

If an additional optional parameter SYSTEM is set to a truthy value, the SYSTEM directory property of the subdirectory added will be set to true. See the add_subdirectory and SYSTEM target property for details.

A shorthand syntax is also supported:

# A git package from a given uri with a version
CPMAddPackage("uri@version")
# A git package from a given uri with a git tag or commit hash
CPMAddPackage("uri#tag")
# A git package with both version and tag provided
CPMAddPackage("uri@version#tag")

In the shorthand syntax if the URI is of the form gh:user/name, it is interpreted as GitHub URI and converted to https://github.com/user/name.git. If the URI is of the form gl:user/name, it is interpreted as a GitLab URI and converted to https://gitlab.com/user/name.git. If the URI is of the form bb:user/name, it is interpreted as a Bitbucket URI and converted to https://bitbucket.org/user/name.git. Otherwise the URI used verbatim as a git URL. All packages added using the shorthand syntax will be added using the EXCLUDE_FROM_ALL and SYSTEM flag.

The single-argument syntax also works for URLs:

# An archive package from a given url. The version is inferred
CPMAddPackage("https://example.com/my-package-1.2.3.zip")
# An archive package from a given url with an MD5 hash provided
CPMAddPackage("https://example.com/my-package-1.2.3.zip#MD5=68e20f674a48be38d60e129f600faf7d")
# An archive package from a given url. The version is explicitly given
CPMAddPackage("https://example.com/my-package.zip@1.2.3")

Supply chain security best practice: For maximum security and reproducibility, always prefer specifying immutable git commit hashes instead of tags or branches when referencing dependencies. Tags and branches can be changed or moved, but commit hashes always refer to the same code. You can specify a commit hash before the version in the URI, e.g. gh:user/repo#<commit>@<version>. This ensures your builds are protected from unexpected upstream changes or attacks.

Additionally, if needed, extra arguments can be provided while using single argument syntax by using the shorthand syntax with the URI specifier.

CPMAddPackage(
  URI "gh:nlohmann/json@3.9.1"
  OPTIONS "JSON_BuildTests OFF"
)

The URI argument must be the first argument to CPMAddPackage. URI automatically sets EXCLUDE_FROM_ALL YES and SYSTEM YES. If this is not desired, EXCLUDE_FROM_ALL NO and SYSTEM NO can be set afterwards.

After calling CPMAddPackage, the following variables are defined in the local scope, where <dependency> is the name of the dependency.

• <dependency>_SOURCE_DIR is the path to the source of the dependency.
• <dependency>_BINARY_DIR is the path to the build directory of the dependency.
• <dependency>_ADDED is set to YES if the dependency has not been added before, otherwise it is set to NO.
• CPM_LAST_PACKAGE_NAME is set to the determined name of the last added dependency (equivalent to <dependency>).

For using CPM.cmake projects with external package managers, such as conan or vcpkg, setting the variable CPM_USE_LOCAL_PACKAGES will make CPM.cmake try to add a package through find_package first, and add it from source if it doesn't succeed.

In rare cases, this behaviour may be desirable by default. The function CPMFindPackage will try to find a local dependency via CMake's find_package and fallback to CPMAddPackage, if the dependency is not found.

Updating CPM

To update CPM to the newest version, update the script in the project's root directory, for example by running the same command as for adding CPM. Dependencies using CPM will automatically use the updated script of the outermost project.

Advantages

• Small and reusable projects CPM takes care of all project dependencies, allowing developers to focus on creating small, well-tested libraries.
• Cross-Platform CPM adds projects directly at the configure stage and is compatible with all CMake toolchains and generators.
• Reproducible builds By versioning dependencies via git commits or tags it is ensured that a project will always be buildable.
• Recursive dependencies Ensures that no dependency is added twice and all are added in the minimum required version.
• Plug-and-play No need to install anything. Just add the script to your project and you're good to go.
• No packaging required Simply add all external sources as a dependency.
• Simple source distribution CPM makes including projects with source files and dependencies easy, reducing the need for monolithic header files or git submodules.

Limitations

• No pre-built binaries For every new build directory, all dependencies are initially downloaded and built from scratch. To avoid extra downloads it is recommend to set the CPM_SOURCE_CACHE environmental variable. Using a caching compiler such as ccache can drastically reduce build time.
• Dependent on good CMakeLists Many libraries do not have CMakeLists that work well for subprojects. Luckily this is slowly changing, however, until then, some manual configuration may be required (see the snippets below for examples). For best practices on preparing projects for CPM, see the wiki.
• First version used In diamond-shaped dependency graphs (e.g. A depends on C@1.1 and B, which itself depends on C@1.2 the first added dependency will be used (in this case C@1.1). In this case, B requires a newer version of C than A, so CPM will emit a warning. This can be easily resolved by adding a new version of the dependency in the outermost project, or by introducing a package lock file.
• Some CMake policies set to NEW Including CPM.cmake will lead to several CMake policies being set to NEW. Users which need the old behavior will need to manually modify their CMake code to ensure they're set to OLD at the appropriate places. The policies are:
  • CMP0077 and CMP0126. They make setting package options from CMPAddPackage possible.
  • CMP0135 It allows for proper package rebuilds of packages which are archives, source cache is not used, and the package URL is changed to an older version.
  • CMP0150 Relative paths provided to GIT_REPOSITORY are treated as relative to the parent project's remote.

For projects with more complex needs and where an extra setup step doesn't matter, it may be worth to check out an external C++ package manager such as [vcpkg](https://