Custom cache directory name (#543)

* Custom cache directory name

Enable setting a custom directory name for cached packages.
Required if e.g. patch_command uses external variables or
just to set a human readable name.

* fixup! review comment CUSTOM_CACHE_DIR -> CUSTOM_CACHE_KEY

* run cmake-format

---------

Co-authored-by: Olsson Gerhard <gerhard.olsson@volvo.com>
Co-authored-by: Lars Melchior <lars.melchior@gmail.com>

.cmake-format

@@ -1,73 +1,5 @@
+include: ["cmake/.cmake-format-additional_commands-cpm"]
 format:
   tab_size: 2
   line_width: 100
   dangle_parens: true
-
-parse:
-  additional_commands:
-    cpmaddpackage:
-      pargs:
-        nargs: '*'
-        flags: []
-      spelling: CPMAddPackage
-      kwargs: &cpmaddpackagekwargs
-        NAME: 1
-        FORCE: 1
-        VERSION: 1
-        GIT_TAG: 1
-        DOWNLOAD_ONLY: 1
-        GITHUB_REPOSITORY: 1
-        GITLAB_REPOSITORY: 1
-        GIT_REPOSITORY: 1
-        SVN_REPOSITORY: 1
-        SVN_REVISION: 1
-        SOURCE_DIR: 1
-        DOWNLOAD_COMMAND: 1
-        FIND_PACKAGE_ARGUMENTS: 1
-        NO_CACHE: 1
-        GIT_SHALLOW: 1
-        URL: 1
-        URL_HASH: 1
-        URL_MD5: 1
-        DOWNLOAD_NAME: 1
-        DOWNLOAD_NO_EXTRACT: 1
-        HTTP_USERNAME: 1
-        HTTP_PASSWORD: 1
-        EXCLUDE_FROM_ALL: 1
-        SOURCE_SUBDIR: 1
-        OPTIONS: +
-    cpmfindpackage:
-      pargs:
-        nargs: '*'
-        flags: []
-      spelling: CPMFindPackage
-      kwargs: *cpmaddpackagekwargs
-    cpmdeclarepackage:
-      pargs:
-        nargs: '*'
-        flags: []
-      spelling: CPMDeclarePackage
-      kwargs: *cpmaddpackagekwargs
-    packageproject:
-      pargs:
-        nargs: '*'
-        flags: []
-      spelling: packageProject
-      kwargs:
-        NAME: 1
-        VERSION: 1
-        INCLUDE_DIR: 1
-        INCLUDE_DESTINATION: 1
-        BINARY_DIR: 1
-        COMPATIBILITY: 1
-        VERSION_HEADER: 1
-        DEPENDENCIES: +
-    cpmusepackagelock:
-      pargs: 1
-      spelling: CPMUsePackageLock
-    cpmregisterpackage:
-      pargs: 1
-      spelling: CPMRegisterPackage
-    cpmgetpackageversion:
-      pargs: 2
-      spelling: CPMGetPackageVersion

.github/workflows/examples.yaml

@@ -12,7 +12,7 @@ jobs:
   gcc:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: build all
         env:
           CC: gcc
@@ -22,7 +22,7 @@ jobs:
   clang:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: build all
         env:
           CC: clang

.github/workflows/publish.yaml

@@ -10,13 +10,14 @@ jobs:
     name: Publish CPM.cmake
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v3
 
       - name: Set CPM version by tag
         run: |
           mkdir dist
-          sed "s/1.0.0-development-version/${GITHUB_REF/refs\/tags\/v}/g" cmake/CPM.cmake > dist/CPM.cmake
-          sed "s/1.0.0-development-version/${GITHUB_REF/refs\/tags\/v}/g" cmake/get_cpm.cmake > dist/get_cpm.cmake
+          sed -e "s/1.0.0-development-version/${GITHUB_REF/refs\/tags\/v}/g" cmake/CPM.cmake > dist/CPM.cmake
+          sed -e "s/1.0.0-development-version/${GITHUB_REF/refs\/tags\/v}/g" \
+              -e "s/CPM_HASH_SUM_PLACEHOLDER/$(sha256sum dist/CPM.cmake | cut -d' ' -f1)/" cmake/get_cpm.cmake > dist/get_cpm.cmake
 
       - name: Upload CPM.cmake to release
         uses: svenstaro/upload-release-action@v1-release

.github/workflows/style.yaml

@@ -14,7 +14,12 @@ jobs:
     runs-on: ubuntu-latest
     
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v3
+
+    - name: Setup cmake
+      uses: jwlawson/actions-setup-cmake@v1.13
+      with:
+        cmake-version: '3.27.x'
     
     - name: Install format dependencies
       run: pip3 install clang-format==14.0.6 cmake_format==0.6.11 pyyaml

.github/workflows/test.yaml

@@ -17,17 +17,32 @@ jobs:
         # we need at least ruby 2.7 for the tests
         # instead of dealing with installing a modern version of ruby on 2019, we'll just use windows-2022 here
         os: [ubuntu-latest, windows-2022, macos-latest]
+        # we want to ensure compatibility with a recent CMake version as well as the lowest officially supported
+        # legacy version that we define as the default version of the second-latest Ubuntu LTS release currently available
+        cmake_version: ['3.16.3', '3.27.5']
+        exclude:
+          # there seems to be an issue with CMake 3.16 not finding a C++ compiler on windows-2022 
+          - os: windows-2022
+            cmake_version: '3.16.3'
 
     steps:
       - name: clone
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
+
+      - name: Setup cmake
+        uses: jwlawson/actions-setup-cmake@v1.13
+        with:
+          cmake-version: ${{ matrix.cmake_version }}
 
       - name: unit tests
         run: |
           cmake -Stest -Bbuild/test
           cmake --build build/test --target test-verbose
+        env:
+          CMAKE_VERSION: ${{ matrix.cmake_version }}
 
       - name: integration tests
         run: ruby test/integration/runner.rb
         env:
           CPM_INTEGRATION_TEST_DIR: ./build/integration
+          CMAKE_VERSION: ${{ matrix.cmake_version }}

CONTRIBUTING.md

@@ -104,7 +104,7 @@ Please try to keep your individual changes as minimal and focussed on the issue
 If you discover that the scope of your contribution is growing larger than expected you might want to split the changes into multiple separate contributions to allow a more focussed discussion and review.
 
 It is usually a great idea and often required to add tests for your changes.
-This allows us to quickly validate that the changes are working as intended and also guarantees that they wont be broken by other future updates.
+This allows us to quickly validate that the changes are working as intended and also guarantees that they won't be broken by other future updates.
 For small and targeted functional changes, e.g. supporting a new URL schema, a [unit test](#unit-tests) may be enough.
 For contributions that change large-scale behaviour, such as dependency caching features, an [integration test](#integration-tests) is more suited.
 Depending on the changes, a combination of both test types may also be appropriate.
@@ -174,4 +174,4 @@ cmake --build build/style --target fix-format
 
 <!-- omit in toc -->
 ## Attribution
-This guide is based on the **contributing-gen**. [Make your own](https://github.com/bttger/contributing-gen)!
+This guide is based on the **contributing-gen**. [Make your own](https://github.com/bttger/contributing-gen)!

README.md

@@ -12,7 +12,7 @@ It's built as a thin wrapper around CMake's [FetchContent](https://cmake.org/cma
 
 ## Manage everything
 
-Any downloadable project or resource can be added as a version-controlled dependency though CPM, it is not necessary to modify or package anything.
+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](#snippets) below for examples).
 
@@ -37,14 +37,26 @@ include(cmake/CPM.cmake)
 
 CPMAddPackage("gh:fmtlib/fmt#7.1.3")
 CPMAddPackage("gh:nlohmann/json@3.10.5")
-CPMAddPackage("gh:catchorg/Catch2@2.5.0")
+CPMAddPackage("gh:catchorg/Catch2@3.4.0")
 
 # link dependencies
-target_link_libraries(main fmt::fmt nlohmann_json::nlohmann_json Catch2::Catch2)
+target_link_libraries(main fmt::fmt nlohmann_json::nlohmann_json Catch2::Catch2WithMain)
 ```
 
 See the [examples directory](https://github.com/cpm-cmake/CPM.cmake/tree/master/examples) for complete examples with source code and check [below](#snippets) or in the [wiki](https://github.com/cpm-cmake/CPM.cmake/wiki/More-Snippets) for example snippets.
 
+## Adding CPM
+
+To add CPM to your current project, simply add the [latest release](https://github.com/cpm-cmake/CPM.cmake/releases/latest) of `CPM.cmake` or `get_cpm.cmake` to your project's `cmake` directory.
+The command below will perform this automatically.
+
+```bash
+mkdir -p cmake
+wget -O cmake/CPM.cmake https://github.com/cpm-cmake/CPM.cmake/releases/latest/download/get_cpm.cmake
+```
+
+You can also download CPM.cmake directly from your project's `CMakeLists.txt`. See the [wiki](https://github.com/cpm-cmake/CPM.cmake/wiki/Downloading-CPM.cmake-in-CMake) for more details.
+
 ## Usage
 
 After `CPM.cmake` has been [added](#adding-cpm) to your project, the function `CPMAddPackage` can be used to fetch and configure a dependency.
@@ -68,6 +80,10 @@ On the other hand, if `VERSION` hasn't been explicitly specified, CPM can automa
 
 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](https://cmake.org/cmake/help/latest/prop_tgt/EXCLUDE_FROM_ALL.html) 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 ](https://cmake.org/cmake/help/latest/command/add_subdirectory.html?highlight=add_subdirectory)
+and [SYSTEM](https://cmake.org/cmake/help/latest/prop_tgt/SYSTEM.html#prop_tgt:SYSTEM) target property for details.
+
 A single-argument compact syntax is also supported:
 
 ```cmake
@@ -79,7 +95,7 @@ CPMAddPackage("uri#tag")
 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](https://gitlab.com/explore/) 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](https://bitbucket.org/) 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](https://cmake.org/cmake/help/latest/prop_tgt/EXCLUDE_FROM_ALL.html) flag.
+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](https://gitlab.com/explore/) 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](https://bitbucket.org/) 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](https://cmake.org/cmake/help/latest/prop_tgt/EXCLUDE_FROM_ALL.html) and [SYSTEM](https://cmake.org/cmake/help/latest/prop_tgt/SYSTEM.html#prop_tgt:SYSTEM) flag.
 
 The single-argument syntax also works for URLs:
 
@@ -103,21 +119,9 @@ For using CPM.cmake projects with external package managers, such as conan or vc
 
 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.
 
-## Adding CPM
-
-To add CPM to your current project, simply add the [latest release](https://github.com/cpm-cmake/CPM.cmake/releases/latest) of `CPM.cmake` or `get_cpm.cmake` to your project's `cmake` directory.
-The command below will perform this automatically.
-
-```bash
-mkdir -p cmake
-wget -O cmake/CPM.cmake https://github.com/cpm-cmake/CPM.cmake/releases/latest/download/get_cpm.cmake
-```
-
-You can also download CPM.cmake directly from your project's `CMakeLists.txt`. See the [wiki](https://github.com/cpm-cmake/CPM.cmake/wiki/Downloading-CPM.cmake-in-CMake) for more details.
-
 ## Updating CPM
 
-To update CPM to the newest version, update the script in the project's root directory, for example by running the command above.
+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](#adding-cpm).
 Dependencies using CPM will automatically use the updated script of the outermost project.
 
 ## Advantages
@@ -138,6 +142,7 @@ Dependencies using CPM will automatically use the updated script of the outermos
 - **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](https://cmake.org/cmake/help/latest/policy/CMP0077.html) and [CMP0126](https://cmake.org/cmake/help/latest/policy/CMP0126.html). They make setting package options from `CMPAddPackage` possible.
     - [CMP0135](https://cmake.org/cmake/help/latest/policy/CMP0135.html) 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](https://cmake.org/cmake/help/latest/policy/CMP0150.html) 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://github.com/microsoft/vcpkg), [conan](https://conan.io) or [hunter](https://github.com/ruslo/hunter).
 Dependencies added with `CPMFindPackage` should work with external package managers.
@@ -185,6 +190,9 @@ Note that passing the variable as a configure option to CMake will always overri
 
 You can use `CPM_SOURCE_CACHE` on GitHub Actions workflows [cache](https://github.com/actions/cache) and combine it with ccache, to make your CI faster. See the [wiki](https://github.com/cpm-cmake/CPM.cmake/wiki/Caching-with-CPM.cmake-and-ccache-on-GitHub-Actions) for more info.
 
+The directory where the version for a project is stored is by default the hash of the arguments to `CPMAddPackage()`.
+If for instance the patch command uses external files, the directory name can be set with the argument `CUSTOM_CACHE_KEY`.
+
 ### CPM_DOWNLOAD_ALL
 
 If set, CPM will forward all calls to `CPMFindPackage` as `CPMAddPackage`.
@@ -195,11 +203,14 @@ This can be controlled on a per package basis with the `CPM_DOWNLOAD_<dependency
 ### CPM_USE_LOCAL_PACKAGES
 
 CPM can be configured to use `find_package` to search for locally installed dependencies first by setting the CMake option `CPM_USE_LOCAL_PACKAGES`.
+
 If the option `CPM_LOCAL_PACKAGES_ONLY` is set, CPM will emit an error if the dependency is not found locally.
 These options can also be set as environmental variables.
 
 In the case that `find_package` requires additional arguments, the parameter `FIND_PACKAGE_ARGUMENTS` may be specified in the `CPMAddPackage` call. The value of this parameter will be forwarded to `find_package`.
 
+Note that this does not apply to dependencies that have been defined with a truthy `FORCE` parameter. These will be added as defined.
+
 ### CPM_USE_NAMED_CACHE_DIRECTORIES
 
 If set, CPM use additional directory level in cache to improve readability of packages names in IDEs like CLion. It changes cache structure, so all dependencies are downloaded again. There is no problem to mix both structures in one cache directory but then there may be 2 copies of some dependencies.
@@ -308,6 +319,58 @@ If you know others, feel free to add them here through a PR.
       </a>
     </td>
   </tr>
+  <tr>
+    <td>
+      <a href="https://github.com/jhasse/jngl">
+        <p align="center">
+          <img src="https://github.com/jhasse/jngl/raw/master/doc/jngl-logo.svg" alt="JNGL" width="100pt" />
+        </p>
+        <p align="center"><b>JNGL - easy to use cross-platform 2D game library</b></p>
+      </a>
+    </td>
+    <td>
+      <a href="https://github.com/sillydan1/aaltitoad">
+        <p align="center">
+          <img src="https://github.com/sillydan1/aaltitoad/raw/v1.1.0/.github/resources/logo/toad_only.svg" alt="aaltitoad" width="100pt" />
+        </p>
+        <p align="center"><b>AALTITOAD - verifier and simulator for Tick Tock Automata</b></p>
+      </a>
+    </td>
+    <td>
+      <a href="https://github.com/ZIMO-Elektronik">
+        <p align="center">
+          <img src="https://avatars.githubusercontent.com/u/117935012?s=400&u=9a871a46dd13437f0adcae166e9efbe518ff0b99&v=4" alt="ZIMO-Elektronik" width="100pt" />
+        </p>
+        <p align="center"><b>ZIMO-Elektronik</b></p>
+      </a>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <a href="https://github.com/ada-url/ada">
+        <p align="center">
+          <img src="https://avatars.githubusercontent.com/u/120840559?s=200&v=4" alt="ada" width="100pt" />
+        </p>
+        <p align="center"><b>ada - WHATWG-compliant and fast URL parser written in modern C++</b></p>
+      </a>
+    </td>
+    <td>
+      <a href="https://github.com/exaloop/codon">
+        <p align="center">
+          <img src="https://github.com/exaloop/codon/blob/develop/docs/img/logo.png?raw=true" alt="codon" width="100pt" />
+        </p>
+        <p align="center"><b>codon - A high-performance, zero-overhead, extensible Python compiler using LLVM</b></p>
+      </a>
+    </td>
+    <td>
+      <a href="https://github.com/RoaringBitmap/CRoaring">
+        <p align="center">
+          <img src="https://avatars.githubusercontent.com/u/16548876?s=200&v=4" alt="CRoaring" width="100pt" />
+        </p>
+        <p align="center"><b>CRoaring - Roaring bitmaps in C (and C++), with SIMD (AVX2, AVX-512 and NEON) optimizations: used by Apache Doris, ClickHouse, and StarRocks</b></p>
+      </a>
+    </td>
+  </tr>
 </table>
 
 ## Snippets
@@ -346,19 +409,27 @@ CPMAddPackage(
 )
 ```
 
-### [Boost ](https://github.com/boostorg/boost)
+### [Boost](https://github.com/boostorg/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.
 
 ```CMake
-# boost is a huge project and will take a while to download
-# using `CPM_SOURCE_CACHE` is strongly recommended
+# 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.77.0
-  GITHUB_REPOSITORY "boostorg/boost"
-  GIT_TAG "boost-1.77.0"
+  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](examples/boost).
+
 ### [cxxopts](https://github.com/jarro2783/cxxopts)
 
 ```cmake
@@ -415,3 +486,85 @@ For a full example on using CPM to download and configure lua with sol2 see [her
 ### Full Examples
 
 See the [examples directory](https://github.com/cpm-cmake/CPM.cmake/tree/master/examples) for full examples with source code and check out the [wiki](https://github.com/cpm-cmake/CPM.cmake/wiki/More-Snippets) 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](https://en.wikipedia.org/wiki/SHA-2) 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](https://github.com/gabime/spdlog) to a project:
+
+```cmake
+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](https://docs.github.com/en/repositories/working-with-files/using-files/downloading-source-code-archives#source-code-archive-urls).
+
+
+#### 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/<user>/<name>/archive/refs/heads/<branch-name>.<archive-type>`
+
+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/<user>/<name>/archive/refs/tags/<tag-name>.<archive-type>`
+
+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/<user>/<name>/archive/<commit-hash>.<archive-type>`
+
+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`:
+```bash
+wget https://github.com/gabime/spdlog/archive/refs/tags/v1.13.0.zip -O - | sha256sum
+```

cmake/.cmake-format-additional_commands-cpm

@@ -0,0 +1,74 @@
+parse:
+  additional_commands:
+    cpmaddpackage:
+      pargs:
+        nargs: '*'
+        flags: []
+      spelling: CPMAddPackage
+      kwargs: &cpmaddpackagekwargs
+        NAME: 1
+        FORCE: 1
+        VERSION: 1
+        GIT_TAG: 1
+        DOWNLOAD_ONLY: 1
+        GITHUB_REPOSITORY: 1
+        GITLAB_REPOSITORY: 1
+        GIT_REPOSITORY: 1
+        SVN_REPOSITORY: 1
+        SVN_REVISION: 1
+        SOURCE_DIR: 1
+        DOWNLOAD_COMMAND: 1
+        FIND_PACKAGE_ARGUMENTS: 1
+        NO_CACHE: 1
+        GIT_SHALLOW: 1
+        URL: 1
+        URL_HASH: 1
+        URL_MD5: 1
+        DOWNLOAD_NAME: 1
+        DOWNLOAD_NO_EXTRACT: 1
+        HTTP_USERNAME: 1
+        HTTP_PASSWORD: 1
+        EXCLUDE_FROM_ALL: 1
+        SYSTEM: 1
+        SOURCE_SUBDIR: 1
+        OPTIONS: +
+    cpmfindpackage:
+      pargs:
+        nargs: '*'
+        flags: []
+      spelling: CPMFindPackage
+      kwargs: *cpmaddpackagekwargs
+    cpmdeclarepackage:
+      pargs:
+        nargs: '*'
+        flags: []
+      spelling: CPMDeclarePackage
+      kwargs: *cpmaddpackagekwargs
+    packageproject:
+      pargs:
+        nargs: '*'
+        flags: []
+      spelling: packageProject
+      kwargs:
+        NAME: 1
+        VERSION: 1
+        NAMESPACE: 1
+        INCLUDE_DIR: 1
+        INCLUDE_DESTINATION: 1
+        INCLUDE_HEADER_PATTERN: 1
+        BINARY_DIR: 1
+        COMPATIBILITY: 1
+        VERSION_HEADER: 1
+        EXPORT_HEADER: 1
+        DISABLE_VERSION_SUFFIX: 1
+        CPACK: 1
+        DEPENDENCIES: +
+    cpmusepackagelock:
+      pargs: 1
+      spelling: CPMUsePackageLock
+    cpmregisterpackage:
+      pargs: 1
+      spelling: CPMRegisterPackage
+    cpmgetpackageversion:
+      pargs: 2
+      spelling: CPMGetPackageVersion

cmake/CPM.cmake

@@ -5,7 +5,7 @@
 # MIT License
 # -----------
 #[[
-  Copyright (c) 2019-2022 Lars Melchior and contributors
+  Copyright (c) 2019-2023 Lars Melchior and contributors
 
   Permission is hereby granted, free of charge, to any person obtaining a copy
   of this software and associated documentation files (the "Software"), to deal
@@ -28,6 +28,20 @@
 
 cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
 
+# Initialize logging prefix
+if(NOT CPM_INDENT)
+  set(CPM_INDENT
+      "CPM:"
+      CACHE INTERNAL ""
+  )
+endif()
+
+if(NOT COMMAND cpm_message)
+  function(cpm_message)
+    message(${ARGV})
+  endfunction()
+endif()
+
 set(CURRENT_CPM_VERSION 1.0.0-development-version)
 
 get_filename_component(CPM_CURRENT_DIRECTORY "${CMAKE_CURRENT_LIST_DIR}" REALPATH)
@@ -59,7 +73,8 @@ See https://github.com/cpm-cmake/CPM.cmake for more information."
 endif()
 
 if(CURRENT_CPM_VERSION MATCHES "development-version")
-  message(WARNING "Your project is using an unstable development version of CPM.cmake. \
+  message(
+    WARNING "${CPM_INDENT} Your project is using an unstable development version of CPM.cmake. \
 Please update to a recent release if possible. \
 See https://github.com/cpm-cmake/CPM.cmake for details."
   )
@@ -84,6 +99,12 @@ macro(cpm_set_policies)
     cmake_policy(SET CMP0135 NEW)
     set(CMAKE_POLICY_DEFAULT_CMP0135 NEW)
   endif()
+
+  # treat relative git repository paths as being relative to the parent project's remote
+  if(POLICY CMP0150)
+    cmake_policy(SET CMP0150 NEW)
+    set(CMAKE_POLICY_DEFAULT_CMP0150 NEW)
+  endif()
 endmacro()
 cpm_set_policies()
 
@@ -223,14 +244,6 @@ function(cpm_package_name_and_ver_from_url url outName outVer)
   endif()
 endfunction()
 
-# Initialize logging prefix
-if(NOT CPM_INDENT)
-  set(CPM_INDENT
-      "CPM:"
-      CACHE INTERNAL ""
-  )
-endif()
-
 function(cpm_find_package NAME VERSION)
   string(REPLACE " " ";" EXTRA_ARGS "${ARGN}")
   find_package(${NAME} ${VERSION} ${EXTRA_ARGS} QUIET)
@@ -238,7 +251,7 @@ function(cpm_find_package NAME VERSION)
     if(DEFINED ${CPM_ARGS_NAME}_VERSION)
       set(VERSION ${${CPM_ARGS_NAME}_VERSION})
     endif()
-    message(STATUS "${CPM_INDENT} using local package ${CPM_ARGS_NAME}@${VERSION}")
+    cpm_message(STATUS "${CPM_INDENT} Using local package ${CPM_ARGS_NAME}@${VERSION}")
     CPMRegisterPackage(${CPM_ARGS_NAME} "${VERSION}")
     set(CPM_PACKAGE_FOUND
         YES
@@ -287,12 +300,6 @@ function(CPMFindPackage)
     return()
   endif()
 
-  cpm_check_if_package_already_added(${CPM_ARGS_NAME} "${CPM_ARGS_VERSION}")
-  if(CPM_PACKAGE_ALREADY_ADDED)
-    cpm_export_variables(${CPM_ARGS_NAME})
-    return()
-  endif()
-
   cpm_find_package(${CPM_ARGS_NAME} "${CPM_ARGS_VERSION}" ${CPM_ARGS_FIND_PACKAGE_ARGUMENTS})
 
   if(NOT CPM_PACKAGE_FOUND)
@@ -309,7 +316,7 @@ function(cpm_check_if_package_already_added CPM_ARGS_NAME CPM_ARGS_VERSION)
     if("${CPM_PACKAGE_VERSION}" VERSION_LESS "${CPM_ARGS_VERSION}")
       message(
         WARNING
-          "${CPM_INDENT} requires a newer version of ${CPM_ARGS_NAME} (${CPM_ARGS_VERSION}) than currently included (${CPM_PACKAGE_VERSION})."
+          "${CPM_INDENT} Requires a newer version of ${CPM_ARGS_NAME} (${CPM_ARGS_VERSION}) than currently included (${CPM_PACKAGE_VERSION})."
       )
     endif()
     cpm_get_fetch_properties(${CPM_ARGS_NAME})
@@ -366,7 +373,7 @@ function(cpm_parse_add_package_single_arg arg outArgs)
       set(packageType "git")
     else()
       # Give up
-      message(FATAL_ERROR "CPM: Can't determine package type of '${arg}'")
+      message(FATAL_ERROR "${CPM_INDENT} Can't determine package type of '${arg}'")
     endif()
   endif()
 
@@ -386,7 +393,7 @@ function(cpm_parse_add_package_single_arg arg outArgs)
   else()
     # We should never get here. This is an assertion and hitting it means there's a bug in the code
     # above. A packageType was set, but not handled by this if-else.
-    message(FATAL_ERROR "CPM: Unsupported package type '${packageType}' of '${arg}'")
+    message(FATAL_ERROR "${CPM_INDENT} Unsupported package type '${packageType}' of '${arg}'")
   endif()
 
   set(${outArgs}
@@ -419,7 +426,7 @@ function(cpm_check_git_working_dir_is_clean repoPath gitTag isClean)
   )
   if(resultGitStatus)
     # not supposed to happen, assume clean anyway
-    message(WARNING "Calling git status on folder ${repoPath} failed")
+    message(WARNING "${CPM_INDENT} Calling git status on folder ${repoPath} failed")
     set(${isClean}
         TRUE
         PARENT_SCOPE
@@ -464,7 +471,7 @@ endfunction()
 function(cpm_override_fetchcontent contentName)
   cmake_parse_arguments(PARSE_ARGV 1 arg "" "SOURCE_DIR;BINARY_DIR" "")
   if(NOT "${arg_UNPARSED_ARGUMENTS}" STREQUAL "")
-    message(FATAL_ERROR "Unsupported arguments: ${arg_UNPARSED_ARGUMENTS}")
+    message(FATAL_ERROR "${CPM_INDENT} Unsupported arguments: ${arg_UNPARSED_ARGUMENTS}")
   endif()
 
   string(TOLOWER ${contentName} contentNameLower)
@@ -506,8 +513,8 @@ function(CPMAddPackage)
   if(argnLength EQUAL 1)
     cpm_parse_add_package_single_arg("${ARGN}" ARGN)
 
-    # The shorthand syntax implies EXCLUDE_FROM_ALL
-    set(ARGN "${ARGN};EXCLUDE_FROM_ALL;YES")
+    # The shorthand syntax implies EXCLUDE_FROM_ALL and SYSTEM
+    set(ARGN "${ARGN};EXCLUDE_FROM_ALL;YES;SYSTEM;YES;")
   endif()
 
   set(oneValueArgs
@@ -521,15 +528,16 @@ function(CPMAddPackage)
       BITBUCKET_REPOSITORY
       GIT_REPOSITORY
       SOURCE_DIR
-      DOWNLOAD_COMMAND
       FIND_PACKAGE_ARGUMENTS
       NO_CACHE
+      SYSTEM
       GIT_SHALLOW
       EXCLUDE_FROM_ALL
       SOURCE_SUBDIR
+      CUSTOM_CACHE_KEY
   )
 
-  set(multiValueArgs URL OPTIONS)
+  set(multiValueArgs URL OPTIONS DOWNLOAD_COMMAND)
 
   cmake_parse_arguments(CPM_ARGS "" "${oneValueArgs}" "${multiValueArgs}" "${ARGN}")
 
@@ -600,7 +608,7 @@ function(CPMAddPackage)
   if(NOT DEFINED CPM_ARGS_NAME)
     message(
       FATAL_ERROR
-        "CPM: 'NAME' was not provided and couldn't be automatically inferred for package added with arguments: '${ARGN}'"
+        "${CPM_INDENT} 'NAME' was not provided and couldn't be automatically inferred for package added with arguments: '${ARGN}'"
     )
   endif()
 
@@ -619,6 +627,7 @@ function(CPMAddPackage)
       NAME "${CPM_ARGS_NAME}"
       SOURCE_DIR "${PACKAGE_SOURCE}"
       EXCLUDE_FROM_ALL "${CPM_ARGS_EXCLUDE_FROM_ALL}"
+      SYSTEM "${CPM_ARGS_SYSTEM}"
       OPTIONS "${CPM_ARGS_OPTIONS}"
       SOURCE_SUBDIR "${CPM_ARGS_SOURCE_SUBDIR}"
       DOWNLOAD_ONLY "${DOWNLOAD_ONLY}"
@@ -639,19 +648,21 @@ function(CPMAddPackage)
     return()
   endif()
 
-  if(CPM_USE_LOCAL_PACKAGES OR CPM_LOCAL_PACKAGES_ONLY)
-    cpm_find_package(${CPM_ARGS_NAME} "${CPM_ARGS_VERSION}" ${CPM_ARGS_FIND_PACKAGE_ARGUMENTS})
+  if(NOT CPM_ARGS_FORCE)
+    if(CPM_USE_LOCAL_PACKAGES OR CPM_LOCAL_PACKAGES_ONLY)
+      cpm_find_package(${CPM_ARGS_NAME} "${CPM_ARGS_VERSION}" ${CPM_ARGS_FIND_PACKAGE_ARGUMENTS})
 
-    if(CPM_PACKAGE_FOUND)
-      cpm_export_variables(${CPM_ARGS_NAME})
-      return()
-    endif()
+      if(CPM_PACKAGE_FOUND)
+        cpm_export_variables(${CPM_ARGS_NAME})
+        return()
+      endif()
 
-    if(CPM_LOCAL_PACKAGES_ONLY)
-      message(
-        SEND_ERROR
-          "CPM: ${CPM_ARGS_NAME} not found via find_package(${CPM_ARGS_NAME} ${CPM_ARGS_VERSION})"
-      )
+      if(CPM_LOCAL_PACKAGES_ONLY)
+        message(
+          SEND_ERROR
+            "${CPM_INDENT} ${CPM_ARGS_NAME} not found via find_package(${CPM_ARGS_NAME} ${CPM_ARGS_VERSION})"
+        )
+      endif()
     endif()
   endif()
 
@@ -694,7 +705,10 @@ function(CPMAddPackage)
     string(TOLOWER ${CPM_ARGS_NAME} lower_case_name)
     set(origin_parameters ${CPM_ARGS_UNPARSED_ARGUMENTS})
     list(SORT origin_parameters)
-    if(CPM_USE_NAMED_CACHE_DIRECTORIES)
+    if(CPM_ARGS_CUSTOM_CACHE_KEY)
+      # Application set a custom unique directory name
+      set(download_directory ${CPM_SOURCE_CACHE}/${lower_case_name}/${CPM_ARGS_CUSTOM_CACHE_KEY})
+    elseif(CPM_USE_NAMED_CACHE_DIRECTORIES)
       string(SHA1 origin_hash "${origin_parameters};NEW_CACHE_STRUCTURE_TAG")
       set(download_directory ${CPM_SOURCE_CACHE}/${lower_case_name}/${origin_hash}/${CPM_ARGS_NAME})
     else()
@@ -705,7 +719,16 @@ function(CPMAddPackage)
     # relative paths.
     get_filename_component(download_directory ${download_directory} ABSOLUTE)
     list(APPEND CPM_ARGS_UNPARSED_ARGUMENTS SOURCE_DIR ${download_directory})
+
+    if(CPM_SOURCE_CACHE)
+      file(LOCK ${download_directory}/../cmake.lock)
+    endif()
+
     if(EXISTS ${download_directory})
+      if(CPM_SOURCE_CACHE)
+        file(LOCK ${download_directory}/../cmake.lock RELEASE)
+      endif()
+
       cpm_store_fetch_properties(
         ${CPM_ARGS_NAME} "${download_directory}"
         "${CPM_FETCHCONTENT_BASE_DIR}/${lower_case_name}-build"
@@ -716,14 +739,20 @@ function(CPMAddPackage)
         # warn if cache has been changed since checkout
         cpm_check_git_working_dir_is_clean(${download_directory} ${CPM_ARGS_GIT_TAG} IS_CLEAN)
         if(NOT ${IS_CLEAN})
-          message(WARNING "Cache for ${CPM_ARGS_NAME} (${download_directory}) is dirty")
+          message(
+            WARNING "${CPM_INDENT} Cache for ${CPM_ARGS_NAME} (${download_directory}) is dirty"
+          )
         endif()
       endif()
 
       cpm_add_subdirectory(
-        "${CPM_ARGS_NAME}" "${DOWNLOAD_ONLY}"
-        "${${CPM_ARGS_NAME}_SOURCE_DIR}/${CPM_ARGS_SOURCE_SUBDIR}" "${${CPM_ARGS_NAME}_BINARY_DIR}"
-        "${CPM_ARGS_EXCLUDE_FROM_ALL}" "${CPM_ARGS_OPTIONS}"
+        "${CPM_ARGS_NAME}"
+        "${DOWNLOAD_ONLY}"
+        "${${CPM_ARGS_NAME}_SOURCE_DIR}/${CPM_ARGS_SOURCE_SUBDIR}"
+        "${${CPM_ARGS_NAME}_BINARY_DIR}"
+        "${CPM_ARGS_EXCLUDE_FROM_ALL}"
+        "${CPM_ARGS_SYSTEM}"
+        "${CPM_ARGS_OPTIONS}"
       )
       set(PACKAGE_INFO "${PACKAGE_INFO} at ${download_directory}")
 
@@ -762,8 +791,8 @@ function(CPMAddPackage)
     endif()
   endif()
 
-  message(
-    STATUS "${CPM_INDENT} adding package ${CPM_ARGS_NAME}@${CPM_ARGS_VERSION} (${PACKAGE_INFO})"
+  cpm_message(
+    STATUS "${CPM_INDENT} Adding package ${CPM_ARGS_NAME}@${CPM_ARGS_VERSION} (${PACKAGE_INFO})"
   )
 
   if(NOT CPM_SKIP_FETCH)
@@ -771,11 +800,18 @@ function(CPMAddPackage)
       "${CPM_ARGS_NAME}" "${CPM_ARGS_VERSION}" "${PACKAGE_INFO}" "${CPM_ARGS_UNPARSED_ARGUMENTS}"
     )
     cpm_fetch_package("${CPM_ARGS_NAME}" populated)
+    if(CPM_SOURCE_CACHE AND download_directory)
+      file(LOCK ${download_directory}/../cmake.lock RELEASE)
+    endif()
     if(${populated})
       cpm_add_subdirectory(
-        "${CPM_ARGS_NAME}" "${DOWNLOAD_ONLY}"
-        "${${CPM_ARGS_NAME}_SOURCE_DIR}/${CPM_ARGS_SOURCE_SUBDIR}" "${${CPM_ARGS_NAME}_BINARY_DIR}"
-        "${CPM_ARGS_EXCLUDE_FROM_ALL}" "${CPM_ARGS_OPTIONS}"
+        "${CPM_ARGS_NAME}"
+        "${DOWNLOAD_ONLY}"
+        "${${CPM_ARGS_NAME}_SOURCE_DIR}/${CPM_ARGS_SOURCE_SUBDIR}"
+        "${${CPM_ARGS_NAME}_BINARY_DIR}"
+        "${CPM_ARGS_EXCLUDE_FROM_ALL}"
+        "${CPM_ARGS_SYSTEM}"
+        "${CPM_ARGS_OPTIONS}"
       )
     endif()
     cpm_get_fetch_properties("${CPM_ARGS_NAME}")
@@ -790,7 +826,7 @@ macro(CPMGetPackage Name)
   if(DEFINED "CPM_DECLARATION_${Name}")
     CPMAddPackage(NAME ${Name})
   else()
-    message(SEND_ERROR "Cannot retrieve package ${Name}: no declaration available")
+    message(SEND_ERROR "${CPM_INDENT} Cannot retrieve package ${Name}: no declaration available")
   endif()
 endmacro()
 
@@ -880,7 +916,7 @@ endfunction()
 # declares a package in FetchContent_Declare
 function(cpm_declare_fetch PACKAGE VERSION INFO)
   if(${CPM_DRY_RUN})
-    message(STATUS "${CPM_INDENT} package not declared (dry run)")
+    cpm_message(STATUS "${CPM_INDENT} Package not declared (dry run)")
     return()
   endif()
 
@@ -926,13 +962,18 @@ function(
   SOURCE_DIR
   BINARY_DIR
   EXCLUDE
+  SYSTEM
   OPTIONS
 )
+
   if(NOT DOWNLOAD_ONLY AND EXISTS ${SOURCE_DIR}/CMakeLists.txt)
+    set(addSubdirectoryExtraArgs "")
     if(EXCLUDE)
-      set(addSubdirectoryExtraArgs EXCLUDE_FROM_ALL)
-    else()
-      set(addSubdirectoryExtraArgs "")
+      list(APPEND addSubdirectoryExtraArgs EXCLUDE_FROM_ALL)
+    endif()
+    if("${SYSTEM}" AND "${CMAKE_VERSION}" VERSION_GREATER_EQUAL "3.25")
+      # https://cmake.org/cmake/help/latest/prop_dir/SYSTEM.html#prop_dir:SYSTEM
+      list(APPEND addSubdirectoryExtraArgs SYSTEM)
     endif()
     if(OPTIONS)
       foreach(OPTION ${OPTIONS})
@@ -955,7 +996,7 @@ function(cpm_fetch_package PACKAGE populated)
       PARENT_SCOPE
   )
   if(${CPM_DRY_RUN})
-    message(STATUS "${CPM_INDENT} package ${PACKAGE} not fetched (dry run)")
+    cpm_message(STATUS "${CPM_INDENT} Package ${PACKAGE} not fetched (dry run)")
     return()
   endif()
 
@@ -1058,14 +1099,17 @@ function(cpm_prettify_package_arguments OUT_VAR IS_IN_COMMENT)
       DOWNLOAD_ONLY
       GITHUB_REPOSITORY
       GITLAB_REPOSITORY
+      BITBUCKET_REPOSITORY
       GIT_REPOSITORY
       SOURCE_DIR
-      DOWNLOAD_COMMAND
       FIND_PACKAGE_ARGUMENTS
       NO_CACHE
+      SYSTEM
       GIT_SHALLOW
+      EXCLUDE_FROM_ALL
+      SOURCE_SUBDIR
   )
-  set(multiValueArgs OPTIONS)
+  set(multiValueArgs URL OPTIONS DOWNLOAD_COMMAND)
   cmake_parse_arguments(CPM_ARGS "" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
 
   foreach(oneArgName ${oneValueArgs})

cmake/get_cpm.cmake

@@ -1,4 +1,9 @@
+# SPDX-License-Identifier: MIT
+#
+# SPDX-FileCopyrightText: Copyright (c) 2019-2023 Lars Melchior and contributors
+
 set(CPM_DOWNLOAD_VERSION 1.0.0-development-version)
+set(CPM_HASH_SUM "CPM_HASH_SUM_PLACEHOLDER")
 
 if(CPM_SOURCE_CACHE)
   set(CPM_DOWNLOAD_LOCATION "${CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
@@ -10,12 +15,10 @@ endif()
 
 # Expand relative path. This is important if the provided path contains a tilde (~)
 get_filename_component(CPM_DOWNLOAD_LOCATION ${CPM_DOWNLOAD_LOCATION} ABSOLUTE)
-if(NOT (EXISTS ${CPM_DOWNLOAD_LOCATION}))
-  message(STATUS "Downloading CPM.cmake to ${CPM_DOWNLOAD_LOCATION}")
-  file(DOWNLOAD
-       https://github.com/cpm-cmake/CPM.cmake/releases/download/v${CPM_DOWNLOAD_VERSION}/CPM.cmake
-       ${CPM_DOWNLOAD_LOCATION}
-  )
-endif()
+
+file(DOWNLOAD
+     https://github.com/cpm-cmake/CPM.cmake/releases/download/v${CPM_DOWNLOAD_VERSION}/CPM.cmake
+     ${CPM_DOWNLOAD_LOCATION} EXPECTED_HASH SHA256=${CPM_HASH_SUM}
+)
 
 include(${CPM_DOWNLOAD_LOCATION})

cmake/testing.cmake

@@ -32,13 +32,13 @@ function(ASSERT_DEFINED KEY)
   if(DEFINED ${KEY})
     message(STATUS "test passed: '${KEY}' is defined")
   else()
-    message(FATAL_ERROR "assertion failed: '${KEY}' is not defiend")
+    message(FATAL_ERROR "assertion failed: '${KEY}' is not defined")
   endif()
 endfunction()
 
 function(ASSERT_NOT_DEFINED KEY)
   if(DEFINED ${KEY})
-    message(FATAL_ERROR "assertion failed: '${KEY}' is defiend (${${KEY}})")
+    message(FATAL_ERROR "assertion failed: '${KEY}' is defined (${${KEY}})")
   else()
     message(STATUS "test passed: '${KEY}' is not defined")
   endif()

examples/benchmark/CMakeLists.txt

@@ -11,7 +11,7 @@ CPMAddPackage("gh:cpm-cmake/testpack-fibonacci@2.0")
 CPMAddPackage(
   NAME benchmark
   GITHUB_REPOSITORY google/benchmark
-  VERSION 1.5.2
+  VERSION 1.7.1
   OPTIONS "BENCHMARK_ENABLE_TESTING Off"
 )
 

examples/boost/CMakeLists.txt

@@ -13,9 +13,10 @@ include(../../cmake/CPM.cmake)
 
 CPMAddPackage(
   NAME Boost
-  VERSION 1.77.0
-  GITHUB_REPOSITORY "boostorg/boost"
-  GIT_TAG "boost-1.77.0"
+  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" "BOOST_INCLUDE_LIBRARIES container\\\;asio" # Note the escapes!
 )
 
-target_link_libraries(CPMExampleBoost PRIVATE Boost::asio)
+target_link_libraries(CPMExampleBoost PRIVATE Boost::asio Boost::container)

examples/boost/main.cpp

@@ -9,18 +9,26 @@
 //
 
 #include <boost/asio.hpp>
+#include <boost/container/devector.hpp>
 #include <boost/date_time/posix_time/posix_time.hpp>
 #include <iostream>
+#include <string>
 
-void print(const boost::system::error_code& /*e*/) { std::cout << "Hello, world!" << std::endl; }
+boost::container::devector<std::string> strings;
+
+void print(const boost::system::error_code& /*e*/) {
+  for (const auto& a : strings) std::cout << a;
+}
 
 int main() {
   boost::asio::io_service io;
 
+  strings.push_back("Hello, world!\n");
+
   boost::asio::deadline_timer t(io, boost::posix_time::seconds(1));
   t.async_wait(&print);
 
   io.run();
 
   return 0;
-}
+}

examples/catch2/CMakeLists.txt

@@ -7,12 +7,12 @@ project(CPMExampleCatch2)
 include(../../cmake/CPM.cmake)
 
 CPMAddPackage("gh:cpm-cmake/testpack-fibonacci@2.0")
-CPMAddPackage("gh:catchorg/Catch2@2.13.4")
+CPMAddPackage("gh:catchorg/Catch2@3.4.0")
 
 # ---- Create binary ----
 
 add_executable(CPMExampleCatch2 main.cpp)
-target_link_libraries(CPMExampleCatch2 fibonacci Catch2)
+target_link_libraries(CPMExampleCatch2 fibonacci Catch2::Catch2WithMain)
 target_compile_features(CPMExampleCatch2 PRIVATE cxx_std_17)
 
 # ---- Enable testing ----

examples/catch2/main.cpp

@@ -1,8 +1,6 @@
-#define CATCH_CONFIG_MAIN
-
 #include <fibonacci.h>
 
-#include <catch2/catch.hpp>
+#include <catch2/catch_test_macros.hpp>
 
 TEST_CASE("fibonacci") {
   REQUIRE(fibonacci(0) == 0);

examples/doctest/CMakeLists.txt

@@ -7,7 +7,7 @@ project(CPMExampleDoctest)
 include(../../cmake/CPM.cmake)
 
 CPMAddPackage("gh:cpm-cmake/testpack-fibonacci@2.0")
-CPMAddPackage("gh:onqtam/doctest#2.4.5")
+CPMAddPackage("gh:onqtam/doctest@2.4.9")
 
 # ---- Create binary ----
 

examples/entt/CMakeLists.txt

@@ -9,8 +9,7 @@ include(../../cmake/CPM.cmake)
 CPMAddPackage(
   NAME EnTT
   VERSION 3.1.1
-  GITHUB_REPOSITORY skypjack/entt
-  # EnTT's CMakeLists screws with configuration options
+  GITHUB_REPOSITORY skypjack/entt # EnTT's CMakeLists screws with configuration options
   DOWNLOAD_ONLY True
 )
 

examples/gtest/CMakeLists.txt

@@ -11,8 +11,8 @@ CPMAddPackage("gh:cpm-cmake/testpack-fibonacci@2.0")
 CPMAddPackage(
   NAME googletest
   GITHUB_REPOSITORY google/googletest
-  GIT_TAG release-1.10.0
-  VERSION 1.10.0
+  GIT_TAG release-1.12.1
+  VERSION 1.12.1
   OPTIONS "INSTALL_GTEST OFF" "gtest_force_shared_crt"
 )
 

examples/linenoise/main.cpp

@@ -56,7 +56,7 @@ int main(int argc, char **argv) {
       int len = atoi(line + 11);
       linenoiseHistorySetMaxLen(len);
     } else if (line[0] == '/') {
-      printf("Unreconized command: %s\n", line);
+      printf("Unrecognized command: %s\n", line);
     }
     free(line);
   }

examples/simdjson/CMakeLists.txt

@@ -0,0 +1,14 @@
+cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
+
+project(CPMSIMDJSONExample)
+
+# ---- Dependencies ----
+
+include(../../cmake/CPM.cmake)
+CPMAddPackage("gh:simdjson/simdjson@3.5.0")
+
+# ---- Executable ----
+
+add_executable(CPMSIMDJSONExample main.cpp)
+target_compile_features(CPMSIMDJSONExample PRIVATE cxx_std_17)
+target_link_libraries(CPMSIMDJSONExample simdjson::simdjson)

examples/simdjson/main.cpp

@@ -0,0 +1,31 @@
+#include <iostream>
+
+#include "simdjson.h"
+using namespace simdjson;
+
+int main() {
+  ondemand::parser parser;
+  auto cars_json = R"( [
+    { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
+    { "make": "Kia",    "model": "Soul",   "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] },
+    { "make": "Toyota", "model": "Tercel", "year": 1999, "tire_pressure": [ 29.8, 30.0, 30.2, 30.5 ] }
+  ] )"_padded;
+
+  // Iterating through an array of objects
+  for (ondemand::object car : parser.iterate(cars_json)) {
+    // Accessing a field by name
+    std::cout << "Make/Model: " << std::string_view(car["make"]) << "/"
+              << std::string_view(car["model"]) << std::endl;
+
+    // Casting a JSON element to an integer
+    uint64_t year = car["year"];
+    std::cout << "- This car is " << 2020 - year << " years old." << std::endl;
+
+    // Iterating through an array of floats
+    double total_tire_pressure = 0;
+    for (double tire_pressure : car["tire_pressure"]) {
+      total_tire_pressure += tire_pressure;
+    }
+    std::cout << "- Average tire pressure: " << (total_tire_pressure / 4) << std::endl;
+  }
+}

examples/sol2/CMakeLists.txt

@@ -15,29 +15,16 @@ CPMAddPackage(
 
 if(lua_ADDED)
   # lua has no CMakeLists, 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 SYSTEM PUBLIC $<BUILD_INTERFACE:${lua_SOURCE_DIR}>)
 endif()
 
-CPMAddPackage(
-  NAME sol2
-  URL https://github.com/ThePhD/sol2/archive/v3.0.2.zip
-  VERSION 3.0.2
-  DOWNLOAD_ONLY YES
-)
-
-if(sol2_ADDED)
-  add_library(sol2 INTERFACE IMPORTED)
-  target_include_directories(sol2 SYSTEM INTERFACE ${sol2_SOURCE_DIR}/include)
-  target_link_libraries(sol2 INTERFACE lua)
-endif()
+CPMAddPackage("gh:ThePhD/sol2@3.3.0")
 
 # ---- Executable ----
 
 add_executable(CPMSol2Example main.cpp)
 target_compile_features(CPMSol2Example PRIVATE cxx_std_17)
-target_link_libraries(CPMSol2Example sol2)
+target_link_libraries(CPMSol2Example sol2 lua)

examples/spdlog/CMakeLists.txt

@@ -8,6 +8,20 @@ include(../../cmake/CPM.cmake)
 
 CPMAddPackage("gh:gabime/spdlog@1.8.2")
 
+# spdlog uses fmt and bundles that dependency. If you want to use fmt in your project as well, you
+# can let spdlog reuse fmt from CPM.cmake like this:
+#
+# cmake-format: off
+#
+# CPMAddPackage("gh:fmtlib/fmt#7.1.3") 
+# CPMAddPackage(
+#   GITHUB_REPOSITORY gabime/spdlog 
+#   VERSION 1.8.2 
+#   OPTIONS "SPDLOG_FMT_EXTERNAL 1" 
+# )
+#
+# cmake-format: on
+
 # ---- Executable ----
 
 add_executable(CPMSpdlogExample main.cpp)

examples/xxHash/CMakeLists.txt

@@ -0,0 +1,20 @@
+cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
+
+project(CPMxxHashExample)
+
+# ---- Dependencies ----
+
+include(../../cmake/CPM.cmake)
+
+CPMAddPackage(
+  GITHUB_REPOSITORY Cyan4973/xxHash
+  GIT_TAG v0.8.2
+  OPTIONS "XXHASH_BUILD_ENABLE_INLINE_API OFF" "XXHASH_BUILD_XXHSUM OFF"
+  SOURCE_SUBDIR cmake_unofficial
+)
+
+# ---- Executable ----
+
+add_executable(CPMxxHashExample main.cpp)
+target_compile_features(CPMxxHashExample PRIVATE cxx_std_17)
+target_link_libraries(CPMxxHashExample xxHash::xxhash)

examples/xxHash/main.cpp

@@ -0,0 +1,12 @@
+#include <xxh3.h>
+
+#include <iostream>
+
+int main() {
+  std::string example = "Hello World!";
+  XXH64_hash_t hash = XXH3_64bits(example.data(), example.size());
+
+  std::cout << "Hash: " << hash << std::endl;
+
+  return 0;
+}

test/integration/README.md

@@ -12,7 +12,7 @@ To run all tests from the repo root execute:
 $ ruby test/integration/runner.rb
 ```
 
-The runner will run all tests and generate a report of the exeuction.
+The runner will run all tests and generate a report of the execution.
 
 The current working directory doesn't matter. If you are in `<repo-root>/test/integration`, you can run simply `$ ruby runner.rb`.
 
@@ -34,7 +34,7 @@ Writing tests makes use of the custom integration test framework in `lib.rb`. It
 * There should be no dependency between the test scripts. Each should be executable individually and the order in which multiple ones are executed mustn't matter.
 * The class should contain methods, also prefixed with `test_` which will be executed by the framework. In most cases there would be a single test method per class.
 * In case there are multiple test methods, they will be executed in the order in which they are defined.
-* The test methods should contain assertions which check for the expected state of things at varous points of the test's execution.
+* The test methods should contain assertions which check for the expected state of things at various points of the test's execution.
 
 ### More
 

test/integration/lib.rb

@@ -143,7 +143,7 @@ class Project
 end
 
 class IntegrationTest < Test::Unit::TestCase
-  self.test_order = :defined # run tests in order of defintion (as opposed to alphabetical)
+  self.test_order = :defined # run tests in order of definition (as opposed to alphabetical)
 
   def cleanup
     # Clear cpm-related env vars which may have been set by the test
@@ -157,6 +157,11 @@ class IntegrationTest < Test::Unit::TestCase
     assert_block(msg) { res.status.success? }
   end
 
+  def assert_failure(res)
+    msg = build_message(nil, "command status was expected to be a failure, but succeeded")
+    assert_block(msg) { !res.status.success? }
+  end
+
   def assert_same_path(a, b)
     msg = build_message(nil, "<?> expected but was\n<?>", a, b)
     assert_block(msg) { File.identical? a, b }
@@ -180,19 +185,20 @@ class IntegrationTest < Test::Unit::TestCase
     @@test_dir
   end
 
-  def make_project(template_dir = nil)
+  def make_project(name: nil, from_template: nil)
     test_name = local_name
     test_name = test_name[5..] if test_name.start_with?('test_')
 
     base = File.join(cur_test_dir, test_name)
+    base += "-#{name}" if name
     src_dir = base + '-src'
 
     FileUtils.mkdir_p src_dir
 
-    if template_dir
-      template_dir = File.join(TestLib::TEMPLATES_DIR, template_dir)
-      raise "#{template_dir} is not a directory" if !File.directory?(template_dir)
-      FileUtils.copy_entry template_dir, src_dir
+    if from_template
+      from_template = File.join(TestLib::TEMPLATES_DIR, from_template)
+      raise "#{from_template} is not a directory" if !File.directory?(from_template)
+      FileUtils.copy_entry from_template, src_dir
     end
 
     Project.new src_dir, base + '-bin'

test/integration/reference.md

@@ -1,4 +1,4 @@
-# Integration Test Framework Refernce
+# Integration Test Framework Reference
 
 ## `TestLib`
 
@@ -60,6 +60,7 @@ The class which must be a parent of all integration test case classes. It itself
 ### Utils
 
 * `cur_test_dir` - the directory of the current test case. A subdirectory of `TestLib::TMP_DIR`
-* `make_project(template_dir = nil)` - create a project from a test method. Will create a the project's source and binary directories as subdirectories of `cur_test_dir`.
-    * Optionally work with a template directory, in which case it will copy the contents of the template directory (one from `templates`) in the project's source directory.
+* `make_project(name: nil, from_template: nil)` - create a project from a test method. Will create the project's source and binary directories as subdirectories of `cur_test_dir`.
+    * Optionally provide a name which will be concatenated to the project directory. This allows creating multiple projects in a test
+    * Optionally work with a template, in which case it will copy the contents of the template directory (one from `templates`) in the project's source directory.
 

test/integration/test_basics.rb

@@ -5,7 +5,7 @@ require_relative './lib'
 class Basics < IntegrationTest
   # Test cpm caches with no cpm-related env vars
   def test_cpm_default
-    prj = make_project 'no-deps'
+    prj = make_project from_template: 'no-deps'
     prj.create_lists_from_default_template
     assert_success prj.configure
 
@@ -38,7 +38,7 @@ class Basics < IntegrationTest
   def test_env_cpm_source_cache
     ENV['CPM_SOURCE_CACHE'] = cur_test_dir
 
-    prj = make_project 'no-deps'
+    prj = make_project from_template: 'no-deps'
     prj.create_lists_from_default_template
     assert_success prj.configure
 

test/integration/test_download_command.rb

@@ -0,0 +1,25 @@
+require_relative './lib'
+
+# Tests using a multi-argumenet download command to fetch a dependency
+
+class DownloadCommand < IntegrationTest
+
+  def test_fetch_dependency_using_download_command
+    prj = make_project from_template: 'using-adder'
+
+    prj.create_lists_from_default_template package: <<~PACK
+      set(DOWNLOAD_DIR ${CMAKE_BINARY_DIR}/_deps/testpack-adder-src)
+      CPMAddPackage(
+        NAME testpack-adder
+        SOURCE_DIR ${DOWNLOAD_DIR}
+        DOWNLOAD_COMMAND git clone --depth 1 --branch v1.0.0 https://github.com/cpm-cmake/testpack-adder.git ${DOWNLOAD_DIR}
+        OPTIONS "ADDER_BUILD_TESTS OFF"
+      )
+    PACK
+
+    # configure with unpopulated cache
+    assert_success prj.configure
+    assert_success prj.build
+  end
+
+end

test/integration/test_fetchcontent_compatibility.rb

@@ -9,8 +9,8 @@ class FetchContentCompatibility < IntegrationTest
   end
 
   def test_add_dependency_cpm_and_fetchcontent
-    prj = make_project 'using-adder'
-    
+    prj = make_project from_template: 'using-adder'
+
     prj.create_lists_from_default_template package: <<~PACK
       CPMAddPackage(
         NAME testpack-adder

test/integration/test_parallelism.rb

@@ -0,0 +1,21 @@
+require_relative './lib'
+
+class Parallelism < IntegrationTest
+  def setup
+    @cache_dir = File.join(cur_test_dir, 'cpmcache')
+    ENV['CPM_SOURCE_CACHE'] = @cache_dir
+  end
+
+  def test_populate_cache_in_parallel
+    4.times.map { |i|
+      prj = make_project name: i.to_s, from_template: 'using-fibadder'
+      prj.create_lists_from_default_template package: 'CPMAddPackage("gh:cpm-cmake/testpack-fibadder@1.0.0")'
+      prj
+    }.map { |prj|
+      Thread.new do
+        assert_success prj.configure
+        assert_success prj.build
+      end
+    }.map(&:join)
+  end
+end

test/integration/test_relative_urls.rb

@@ -0,0 +1,17 @@
+require_relative './lib'
+
+class RelativeURLs < IntegrationTest
+  def setup
+    # relative URLs were introduced in CMake 3.27
+    @relative_urls_supported = (!ENV['CMAKE_VERSION']) || (Gem::Version.new(ENV['CMAKE_VERSION']) >= Gem::Version.new('3.27'))
+  end
+
+  def test_add_project_with_relative_urls
+    omit_if !@relative_urls_supported do
+      prj = make_project from_template: 'using-fibadder'
+      prj.create_lists_from_default_template package: 'CPMAddPackage("gh:cpm-cmake/testpack-fibadder@1.1.0-relative-urls")'
+      assert_success prj.configure
+      assert_success prj.build
+    end
+  end
+end

test/integration/test_remove_source_dir.rb

@@ -2,8 +2,8 @@ require_relative './lib'
 
 class RemoveSourceDir < IntegrationTest
   def test_remove_source_dir
-    prj = make_project 'using-adder'
-    
+    prj = make_project from_template: 'using-adder'
+
     prj.create_lists_from_default_template package: <<~PACK
       CPMAddPackage(
         NAME testpack-adder

test/integration/test_simple.rb

@@ -4,7 +4,7 @@ class Simple < IntegrationTest
   ADDER_PACKAGE_NAME = 'testpack-adder'
 
   def test_update_single_package
-    prj = make_project 'using-adder'
+    prj = make_project from_template: 'using-adder'
     adder_cache0 = nil
     adder_ver_file = nil
 
@@ -70,7 +70,7 @@ class Simple < IntegrationTest
 
       exes = Dir[exe_dir + '/**/*'].filter {
         # on multi-configuration generators (like Visual Studio) the executables will be in bin/<Config>
-        # also filter-out other articacts like .pdb or .dsym
+        # also filter-out other artifacts like .pdb or .dsym
         !File.directory?(_1) && File.stat(_1).executable?
       }.map {
         # remove .exe extension if any (there will be one on Windows)

test/integration/test_source_cache.rb

@@ -9,7 +9,7 @@ class SourceCache < IntegrationTest
   end
 
   def test_add_remove_dependency
-    prj = make_project 'using-fibadder'
+    prj = make_project from_template: 'using-fibadder'
 
     ###################################
     # create
@@ -45,7 +45,7 @@ class SourceCache < IntegrationTest
   end
 
   def test_second_project
-    prj = make_project 'using-fibadder'
+    prj = make_project from_template: 'using-fibadder'
     prj.create_lists_from_default_template package: 'CPMAddPackage("gh:cpm-cmake/testpack-fibadder@1.1.0")'
     assert_success prj.configure
 

test/integration/test_system_warnings.rb

@@ -0,0 +1,57 @@
+require_relative './lib'
+
+class SystemWarnings < IntegrationTest
+  
+  def setup
+    # system is only supported for CMake >= 3.25 
+    @system_supported = (!ENV['CMAKE_VERSION']) || (Gem::Version.new(ENV['CMAKE_VERSION']) >= Gem::Version.new('3.25'))
+  end
+
+  def test_dependency_added_using_system
+    for use_system in [true, false] do
+      prj = make_project name: use_system ? "system" : "no_system", from_template: 'using-adder'
+      prj.create_lists_from_default_template package: <<~PACK
+        # this commit has a warning in a public header
+        CPMAddPackage(
+          NAME Adder
+          GITHUB_REPOSITORY cpm-cmake/testpack-adder
+          GIT_TAG v1.0.1-warnings
+          SYSTEM #{use_system ? "YES" : "NO"}
+        )
+        # all packages using `adder` will error on warnings
+        target_compile_options(adder INTERFACE
+          $<$<CXX_COMPILER_ID:MSVC>:/Wall /WX>
+          $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-Wall -Werror>
+        )
+      PACK
+
+      assert_success prj.configure
+      if use_system and @system_supported
+        assert_success prj.build
+      else
+        assert_failure prj.build
+      end
+    end
+  end
+  
+  def test_dependency_added_implicitly_using_system
+    prj = make_project from_template: 'using-adder'
+    prj.create_lists_from_default_template package: <<~PACK
+      # this commit has a warning in a public header
+      CPMAddPackage("gh:cpm-cmake/testpack-adder@1.0.1-warnings")
+      # all packages using `adder` will error on warnings
+      target_compile_options(adder INTERFACE
+        $<$<CXX_COMPILER_ID:MSVC>:/Wall /WX>
+        $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-Wall -Werror>
+      )
+    PACK
+
+    assert_success prj.configure
+    if @system_supported
+      assert_success prj.build
+    else
+      assert_failure prj.build
+    end
+  end
+
+end

test/integration/tutorial.md

@@ -14,7 +14,7 @@ class MyTest < IntegrationTest
 end
 ```
 
-Now we have our test case class, and the single test method that we will require. Let's focus on the method's contents. The integration test framework provides us with a helper class, `Project`, which can be used for this scenario. A project has an assoiciated pair of source and binary directories in the temporary directory and it provides methods to work with them.
+Now we have our test case class, and the single test method that we will require. Let's focus on the method's contents. The integration test framework provides us with a helper class, `Project`, which can be used for this scenario. A project has an associated pair of source and binary directories in the temporary directory and it provides methods to work with them.
 
 We start by creating the project:
 

test/unit/cache.cmake

@@ -26,6 +26,17 @@ function(reset_test)
   update_cmake_lists()
 endfunction()
 
+function(assert_cache_directory_count directory count)
+  set(version_count 0)
+  file(GLOB potential_versions ${directory})
+  foreach(entry ${potential_versions})
+    if(IS_DIRECTORY ${entry})
+      math(EXPR version_count "${version_count} + 1")
+    endif()
+  endforeach()
+  assert_equal("${version_count}" "${count}")
+endfunction()
+
 set(FIBONACCI_VERSION 1.0)
 
 # Read CPM_SOURCE_CACHE from arguments
@@ -40,13 +51,7 @@ execute_process(
 assert_equal(${ret} "0")
 assert_exists("${CPM_SOURCE_CACHE_DIR}/fibonacci")
 
-file(GLOB FIBONACCI_VERSIONs "${CPM_SOURCE_CACHE_DIR}/fibonacci/*")
-list(LENGTH FIBONACCI_VERSIONs FIBONACCI_VERSION_count)
-assert_equal(${FIBONACCI_VERSION_count} "1")
-
-file(GLOB fibonacci_versions "${CPM_SOURCE_CACHE_DIR}/fibonacci/*")
-list(LENGTH fibonacci_versions fibonacci_version_count)
-assert_equal(${fibonacci_version_count} "1")
+assert_cache_directory_count("${CPM_SOURCE_CACHE_DIR}/fibonacci/*" 1)
 
 # Update dependency and keep CPM_SOURCE_CACHE
 
@@ -54,12 +59,9 @@ set(FIBONACCI_VERSION 2.0)
 update_cmake_lists()
 
 execute_process(COMMAND ${CMAKE_COMMAND} ${TEST_BUILD_DIR} RESULT_VARIABLE ret)
-
 assert_equal(${ret} "0")
 
-file(GLOB FIBONACCI_VERSIONs "${CPM_SOURCE_CACHE_DIR}/fibonacci/*")
-list(LENGTH FIBONACCI_VERSIONs FIBONACCI_VERSION_count)
-assert_equal(${FIBONACCI_VERSION_count} "2")
+assert_cache_directory_count("${CPM_SOURCE_CACHE_DIR}/fibonacci/*" 2)
 
 # Clear cache and update
 
@@ -135,3 +137,19 @@ execute_process(
 
 assert_equal(${ret} "0")
 assert_not_exists("${CPM_SOURCE_CACHE_DIR}/fibonacci")
+
+# Use custom cache directory
+
+set(FIBONACCI_PACKAGE_ARGS
+    "CUSTOM_CACHE_KEY my_custom_unique_dir GIT_TAG e9ebf168ca0fffaa4ef8c6fefc6346aaa22f6ed5"
+)
+set(FIBONACCI_VERSION 1.1)
+update_cmake_lists()
+
+execute_process(
+  COMMAND ${CMAKE_COMMAND} -E env "CPM_SOURCE_CACHE=${CPM_SOURCE_CACHE_DIR}" ${CMAKE_COMMAND}
+          "-S${CMAKE_CURRENT_LIST_DIR}/remote_dependency" "-B${TEST_BUILD_DIR}" RESULT_VARIABLE ret
+)
+
+assert_equal(${ret} "0")
+assert_exists("${CPM_SOURCE_CACHE_DIR}/fibonacci/my_custom_unique_dir")