CPM.cmake

klogg - fast advanced log explorer

JNGL - easy to use cross-platform 2D game library

AALTITOAD - verifier and simulator for Tick Tock Automata

ZIMO-Elektronik

ada - WHATWG-compliant and fast URL parser written in modern C++

codon - A high-performance, zero-overhead, extensible Python compiler using LLVM

CRoaring - Roaring bitmaps in C (and C++), with SIMD (AVX2, AVX-512 and NEON) optimizations: used by Apache Doris, ClickHouse, and StarRocks

Snippets

These examples demonstrate how to include some well-known projects with CPM. See the wiki for more snippets.

Catch2

CPMAddPackage("gh:catchorg/[email protected]")

Range-v3

CPMAddPackage("gh:ericniebler/range-v3#0.12.0")

Yaml-cpp

# as the tag is in an unusual format, we need to explicitly specify the version
CPMAddPackage("gh:jbeder/yaml-cpp#[email protected]")

nlohmann/json

CPMAddPackage(
  NAME nlohmann_json
  VERSION 3.9.1
  GITHUB_REPOSITORY nlohmann/json
  OPTIONS
    "JSON_BuildTests OFF"
)

Boost

Boost is a large project and will take a while to download. Using CPM_SOURCE_CACHE is strongly recommended. Cloning moves much more data than a source archive, so this sample will use a compressed source archive (tar.xz) release from Boost's github page.

# boost is a huge project and directly downloading the 'alternate release'
# from github is much faster than recursively cloning the repo.
CPMAddPackage(
  NAME Boost
  VERSION 1.84.0
  URL https://github.com/boostorg/boost/releases/download/boost-1.84.0/boost-1.84.0.tar.xz
  URL_HASH SHA256=2e64e5d79a738d0fa6fb546c6e5c2bd28f88d268a2a080546f74e5ff98f29d0e
  OPTIONS "BOOST_ENABLE_CMAKE ON"
)

For a working example of using CPM to download and configure the Boost C++ Libraries see here.

cxxopts

# the install option has to be explicitly set to allow installation
CPMAddPackage(
  GITHUB_REPOSITORY jarro2783/cxxopts
  VERSION 2.2.1
  OPTIONS "CXXOPTS_BUILD_EXAMPLES NO" "CXXOPTS_BUILD_TESTS NO" "CXXOPTS_ENABLE_INSTALL YES"
)

google/benchmark

CPMAddPackage(
  NAME benchmark
  GITHUB_REPOSITORY google/benchmark
  VERSION 1.5.2
  OPTIONS "BENCHMARK_ENABLE_TESTING Off"
)

if(benchmark_ADDED)
  # enable c++11 to avoid compilation errors
  set_target_properties(benchmark PROPERTIES CXX_STANDARD 11)
endif()

Lua

) endif()">

CPMAddPackage(
  NAME lua
  GIT_REPOSITORY https://github.com/lua/lua.git
  VERSION 5.3.5
  DOWNLOAD_ONLY YES
)

if (lua_ADDED)
  # lua has no CMake support, so we create our own target

  FILE(GLOB lua_sources ${lua_SOURCE_DIR}/*.c)
  list(REMOVE_ITEM lua_sources "${lua_SOURCE_DIR}/lua.c" "${lua_SOURCE_DIR}/luac.c")
  add_library(lua STATIC ${lua_sources})

  target_include_directories(lua
    PUBLIC
      $<BUILD_INTERFACE:${lua_SOURCE_DIR}>
  )
endif()

For a full example on using CPM to download and configure lua with sol2 see here.

Full Examples

See the examples directory for full examples with source code and check out the wiki for many more example snippets.

Source Archives from GitHub

Using a compressed source archive is usually much faster than a shallow clone. Optionally, you can verify the integrity using SHA256 or similar. Setting the hash is useful to ensure a specific source is imported, especially since tags, branches, and archives can change.

Let's look at adding spdlog to a project:

CPMAddPackage(
  NAME     spdlog
  URL      https://github.com/gabime/spdlog/archive/refs/tags/v1.12.0.zip
  URL_HASH SHA256=6174bf8885287422a6c6a0312eb8a30e8d22bcfcee7c48a6d02d1835d7769232
)

URL_HASH is optional, but it's a good idea for releases.

Identifying the URL

Information for determining the URL is found here.

Release

Not every software package provides releases, but for those that do, they can be found on the release page of the project. In a browser, the URL of the specific release is determined in a browser is determined by right clicking and selecting Copy link address (or similar) for the desired release. This is the value you will use in the URL section.

This is the URL for spdlog release 1.13.0 in zip format: https://github.com/gabime/spdlog/archive/refs/tags/v1.13.0.zip

Branch

The URL for branches is non-obvious from a browser. But it's still fairly easy to figure it out. The format is as follows:

https://github.com///archive/refs/heads/.

Archive type can be one of tar.gz or zip.

The URL for branch v2.x of spdlog is: https://github.com/gabime/spdlog/archive/refs/heads/v2.x.tar.gz

Tag

Tags are similar, but with this format:

https://github.com///archive/refs/tags/.

Tag v1.8.5 of spdlog is this:

https://github.com/gabime/spdlog/archive/refs/tags/v1.8.5.tar.gz

Exactly like the release.

Commit

If a specific commit contains the code you need, it's defined as follows:

https://github.com///archive/.

Example: https://github.com/gabime/spdlog/archive/c1569a3d293a6b511ecb9c18b2298826c9578d9f.tar.gz

Determining the Hash

The following snippet illustrates determining the SHA256 hash on a linux machine using wget and sha256sum:

wget https://github.com/gabime/spdlog/archive/refs/tags/v1.13.0.zip -O - | sha256sum