Implement #624: Use shorter hashes with CPM_SOURCE_CACHE (#631)

* Add ASSERT_CONTENTS_EQUAL test macro in testing.cmake

Checks if the contents of a file matches the given input

* Use shorter hashes with CPM_SOURCE_CACHE (#624)

Uses shorter hashes with CPM_SOURCE_CACHE. Falls back to a longer hash
if necessary (ie, if there's a collision with an existing hash).

See: https://github.com/cpm-cmake/CPM.cmake/issues/624

* Update integration tests to support shorter hashes

* trigger ci

* run cmake-format

* if already available, use the legacy cache hash

* create temporary file in current binary dir

* add test case for legacy hash

---------

Co-authored-by: Lars Melchior <lars.melchior@gmail.com>
Co-authored-by: Lars Melchior <TheLartians@users.noreply.github.com>

.git_archival.txt

@@ -0,0 +1,3 @@
+node: $Format:%H$
+node-date: $Format:%cI$
+describe-name: $Format:%(describe:tags=true,match=?[0-9.]*)$

.gitattributes

@@ -0,0 +1 @@
+.git_archival.txt  export-subst

.github/workflows/test.yaml

@@ -19,7 +19,7 @@ jobs:
         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']
+        cmake_version: ['3.16.3', '3.27.5', '3.30.0']
         exclude:
           # there seems to be an issue with CMake 3.16 not finding a C++ compiler on windows-2022 
           - os: windows-2022

CMakeLists.txt

@@ -0,0 +1,28 @@
+cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
+
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/.git/")
+  find_package(Git REQUIRED)
+  execute_process(
+    COMMAND "${GIT_EXECUTABLE}" describe --tags --match=?[0-9.]*
+    WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+    OUTPUT_VARIABLE DESCRIBE_NAME COMMAND_ERROR_IS_FATAL ANY
+  )
+  set(CPM_DEVELOPMENT "-development-version")
+else()
+  file(STRINGS "${CMAKE_CURRENT_SOURCE_DIR}/.git_archival.txt" DESCRIBE_NAME
+       REGEX "^describe-name:.*"
+  )
+endif()
+
+string(REGEX MATCH "([0-9\\.]+)" EXTRACTED_CPM_VERSION "${DESCRIBE_NAME}")
+
+project(
+  CPM.cmake
+  VERSION "${EXTRACTED_CPM_VERSION}"
+  DESCRIPTION
+    "CMake's missing package manager. A small CMake script for setup-free, cross-platform, reproducible dependency management."
+  HOMEPAGE_URL "https://github.com/cpm-cmake/CPM.cmake"
+  LANGUAGES NONE
+)
+
+include("${CMAKE_CURRENT_SOURCE_DIR}/cmake/CPM.cmake")

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.

README.md

@@ -67,6 +67,7 @@ Afterwards, any targets defined in the dependency can be used directly.
 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, the project is downloaded, but not configured (optional)
   [...]         # Origin parameters forwarded to FetchContent_Declare, see below
@@ -78,13 +79,16 @@ If `GIT_TAG` hasn't been explicitly specified it defaults to `v(VERSION)`, a com
 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](examples/highway/CMakeLists.txt).
+We recommend that if you use `PATCHES`, you also set `CPM_SOURCE_CACHE`. See [issue 577](https://github.com/cpm-cmake/CPM.cmake/issues/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](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:
+A shorthand syntax is also supported:
 
 ```cmake
 # A git package from a given uri with a version
@@ -108,6 +112,19 @@ CPMAddPackage("https://example.com/my-package-1.2.3.zip#MD5=68e20f674a48be38d60e
 CPMAddPackage("https://example.com/my-package.zip@1.2.3")
 ```
 
+Additionally, if needed, extra arguments can be provided while using single argument syntax by using the shorthand syntax with the `URI` specifier.
+
+```cmake
+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.
@@ -190,6 +207,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`.
@@ -208,6 +228,13 @@ In the case that `find_package` requires additional arguments, the parameter `FI
 
 Note that this does not apply to dependencies that have been defined with a truthy `FORCE` parameter. These will be added as defined.
 
+### CPM_DONT_UPDATE_MODULE_PATH
+
+By default, CPM will override any `find_package` commands to use the CPM downloaded version.
+This is equivalent to the `OVERRIDE_FIND_PACKAGE` FetchContent option, which has no effect in CPM.
+To disable this behaviour set the `CPM_DONT_UPDATE_MODULE_PATH` option.
+This will not work for `find_package(CONFIG)` in CMake versions before 3.24.
+
 ### 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.
@@ -398,34 +425,38 @@ CPMAddPackage("gh:jbeder/yaml-cpp#yaml-cpp-0.6.3@0.6.3")
 
 ```cmake
 CPMAddPackage(
-  NAME nlohmann_json
-  VERSION 3.9.1
-  GITHUB_REPOSITORY nlohmann/json
-  OPTIONS
-    "JSON_BuildTests OFF"
+  URI "gh:nlohmann/json@3.9.1"
+  OPTIONS "JSON_BuildTests OFF"
 )
 ```
 
-### [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.81.0
-  GITHUB_REPOSITORY "boostorg/boost"
-  GIT_TAG "boost-1.81.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
 # the install option has to be explicitly set to allow installation
 CPMAddPackage(
-  GITHUB_REPOSITORY jarro2783/cxxopts
-  VERSION 2.2.1
+  URI "gh:jarro2783/cxxopts@2.2.1"
   OPTIONS "CXXOPTS_BUILD_EXAMPLES NO" "CXXOPTS_BUILD_TESTS NO" "CXXOPTS_ENABLE_INSTALL YES"
 )
 ```
@@ -434,9 +465,7 @@ CPMAddPackage(
 
 ```cmake
 CPMAddPackage(
-  NAME benchmark
-  GITHUB_REPOSITORY google/benchmark
-  VERSION 1.5.2
+  URI "gh:google/benchmark@1.5.2"
   OPTIONS "BENCHMARK_ENABLE_TESTING Off"
 )
 
@@ -475,3 +504,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

@@ -31,6 +31,7 @@ parse:
         EXCLUDE_FROM_ALL: 1
         SYSTEM: 1
         SOURCE_SUBDIR: 1
+        PATCHES: +
         OPTIONS: +
     cpmfindpackage:
       pargs:
@@ -52,11 +53,16 @@ parse:
       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

cmake/CPM.cmake

@@ -42,7 +42,11 @@ if(NOT COMMAND cpm_message)
   endfunction()
 endif()
 
-set(CURRENT_CPM_VERSION 1.0.0-development-version)
+if(DEFINED EXTRACTED_CPM_VERSION)
+  set(CURRENT_CPM_VERSION "${EXTRACTED_CPM_VERSION}${CPM_DEVELOPMENT}")
+else()
+  set(CURRENT_CPM_VERSION 1.0.0-development-version)
+endif()
 
 get_filename_component(CPM_CURRENT_DIRECTORY "${CMAKE_CURRENT_LIST_DIR}" REALPATH)
 if(CPM_DIRECTORY)
@@ -162,7 +166,7 @@ set(CPM_SOURCE_CACHE
     CACHE PATH "Directory to download CPM dependencies"
 )
 
-if(NOT CPM_DONT_UPDATE_MODULE_PATH)
+if(NOT CPM_DONT_UPDATE_MODULE_PATH AND NOT DEFINED CMAKE_FIND_PACKAGE_REDIRECTS_DIR)
   set(CPM_MODULE_PATH
       "${CMAKE_BINARY_DIR}/CPM_modules"
       CACHE INTERNAL ""
@@ -198,6 +202,60 @@ function(cpm_package_name_from_git_uri URI RESULT)
   endif()
 endfunction()
 
+# Find the shortest hash that can be used eg, if origin_hash is
+# cccb77ae9609d2768ed80dd42cec54f77b1f1455 the following files will be checked, until one is found
+# that is either empty (allowing us to assign origin_hash), or whose contents matches ${origin_hash}
+#
+# * .../cccb.hash
+# * .../cccb77ae.hash
+# * .../cccb77ae9609.hash
+# * .../cccb77ae9609d276.hash
+# * etc
+#
+# We will be able to use a shorter path with very high probability, but in the (rare) event that the
+# first couple characters collide, we will check longer and longer substrings.
+function(cpm_get_shortest_hash source_cache_dir origin_hash short_hash_output_var)
+  # for compatibility with caches populated by a previous version of CPM, check if a directory using
+  # the full hash already exists
+  if(EXISTS "${source_cache_dir}/${origin_hash}")
+    set(${short_hash_output_var}
+        "${origin_hash}"
+        PARENT_SCOPE
+    )
+    return()
+  endif()
+
+  foreach(len RANGE 4 40 4)
+    string(SUBSTRING "${origin_hash}" 0 ${len} short_hash)
+    set(hash_lock ${source_cache_dir}/${short_hash}.lock)
+    set(hash_fp ${source_cache_dir}/${short_hash}.hash)
+    # Take a lock, so we don't have a race condition with another instance of cmake. We will release
+    # this lock when we can, however, if there is an error, we want to ensure it gets released on
+    # it's own on exit from the function.
+    file(LOCK ${hash_lock} GUARD FUNCTION)
+
+    # Load the contents of .../${short_hash}.hash
+    file(TOUCH ${hash_fp})
+    file(READ ${hash_fp} hash_fp_contents)
+
+    if(hash_fp_contents STREQUAL "")
+      # Write the origin hash
+      file(WRITE ${hash_fp} ${origin_hash})
+      file(LOCK ${hash_lock} RELEASE)
+      break()
+    elseif(hash_fp_contents STREQUAL origin_hash)
+      file(LOCK ${hash_lock} RELEASE)
+      break()
+    else()
+      file(LOCK ${hash_lock} RELEASE)
+    endif()
+  endforeach()
+  set(${short_hash_output_var}
+      "${short_hash}"
+      PARENT_SCOPE
+  )
+endfunction()
+
 # Try to infer package name and version from a url
 function(cpm_package_name_and_ver_from_url url outName outVer)
   if(url MATCHES "[/\\?]([a-zA-Z0-9_\\.-]+)\\.(tar|tar\\.gz|tar\\.bz2|zip|ZIP)(\\?|/|$)")
@@ -269,10 +327,25 @@ endfunction()
 # finding the system library
 function(cpm_create_module_file Name)
   if(NOT CPM_DONT_UPDATE_MODULE_PATH)
-    # erase any previous modules
-    file(WRITE ${CPM_MODULE_PATH}/Find${Name}.cmake
-         "include(\"${CPM_FILE}\")\n${ARGN}\nset(${Name}_FOUND TRUE)"
-    )
+    if(DEFINED CMAKE_FIND_PACKAGE_REDIRECTS_DIR)
+      # Redirect find_package calls to the CPM package. This is what FetchContent does when you set
+      # OVERRIDE_FIND_PACKAGE. The CMAKE_FIND_PACKAGE_REDIRECTS_DIR works for find_package in CONFIG
+      # mode, unlike the Find${Name}.cmake fallback. CMAKE_FIND_PACKAGE_REDIRECTS_DIR is not defined
+      # in script mode, or in CMake < 3.24.
+      # https://cmake.org/cmake/help/latest/module/FetchContent.html#fetchcontent-find-package-integration-examples
+      string(TOLOWER ${Name} NameLower)
+      file(WRITE ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/${NameLower}-config.cmake
+           "include(\"\${CMAKE_CURRENT_LIST_DIR}/${NameLower}-extra.cmake\" OPTIONAL)\n"
+           "include(\"\${CMAKE_CURRENT_LIST_DIR}/${Name}Extra.cmake\" OPTIONAL)\n"
+      )
+      file(WRITE ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/${NameLower}-config-version.cmake
+           "set(PACKAGE_VERSION_COMPATIBLE TRUE)\n" "set(PACKAGE_VERSION_EXACT TRUE)\n"
+      )
+    else()
+      file(WRITE ${CPM_MODULE_PATH}/Find${Name}.cmake
+           "include(\"${CPM_FILE}\")\n${ARGN}\nset(${Name}_FOUND TRUE)"
+      )
+    endif()
   endif()
 endfunction()
 
@@ -300,12 +373,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)
@@ -397,8 +464,8 @@ function(cpm_parse_add_package_single_arg arg outArgs)
     # We don't try to parse the version if it's not provided explicitly. cpm_get_version_from_url
     # should do this at a later point
   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.
+    # We should never get here. This is an assertion and hitting it means there's a problem with the
+    # code above. A packageType was set, but not handled by this if-else.
     message(FATAL_ERROR "${CPM_INDENT} Unsupported package type '${packageType}' of '${arg}'")
   endif()
 
@@ -470,6 +537,72 @@ function(cpm_check_git_working_dir_is_clean repoPath gitTag isClean)
 
 endfunction()
 
+# Add PATCH_COMMAND to CPM_ARGS_UNPARSED_ARGUMENTS. This method consumes a list of files in ARGN
+# then generates a `PATCH_COMMAND` appropriate for `ExternalProject_Add()`. This command is appended
+# to the parent scope's `CPM_ARGS_UNPARSED_ARGUMENTS`.
+function(cpm_add_patches)
+  # Return if no patch files are supplied.
+  if(NOT ARGN)
+    return()
+  endif()
+
+  # Find the patch program.
+  find_program(PATCH_EXECUTABLE patch)
+  if(CMAKE_HOST_WIN32 AND NOT PATCH_EXECUTABLE)
+    # The Windows git executable is distributed with patch.exe. Find the path to the executable, if
+    # it exists, then search `../usr/bin` and `../../usr/bin` for patch.exe.
+    find_package(Git QUIET)
+    if(GIT_EXECUTABLE)
+      get_filename_component(extra_search_path ${GIT_EXECUTABLE} DIRECTORY)
+      get_filename_component(extra_search_path_1up ${extra_search_path} DIRECTORY)
+      get_filename_component(extra_search_path_2up ${extra_search_path_1up} DIRECTORY)
+      find_program(
+        PATCH_EXECUTABLE patch HINTS "${extra_search_path_1up}/usr/bin"
+                                     "${extra_search_path_2up}/usr/bin"
+      )
+    endif()
+  endif()
+  if(NOT PATCH_EXECUTABLE)
+    message(FATAL_ERROR "Couldn't find `patch` executable to use with PATCHES keyword.")
+  endif()
+
+  # Create a temporary
+  set(temp_list ${CPM_ARGS_UNPARSED_ARGUMENTS})
+
+  # Ensure each file exists (or error out) and add it to the list.
+  set(first_item True)
+  foreach(PATCH_FILE ${ARGN})
+    # Make sure the patch file exists, if we can't find it, try again in the current directory.
+    if(NOT EXISTS "${PATCH_FILE}")
+      if(NOT EXISTS "${CMAKE_CURRENT_LIST_DIR}/${PATCH_FILE}")
+        message(FATAL_ERROR "Couldn't find patch file: '${PATCH_FILE}'")
+      endif()
+      set(PATCH_FILE "${CMAKE_CURRENT_LIST_DIR}/${PATCH_FILE}")
+    endif()
+
+    # Convert to absolute path for use with patch file command.
+    get_filename_component(PATCH_FILE "${PATCH_FILE}" ABSOLUTE)
+
+    # The first patch entry must be preceded by "PATCH_COMMAND" while the following items are
+    # preceded by "&&".
+    if(first_item)
+      set(first_item False)
+      list(APPEND temp_list "PATCH_COMMAND")
+    else()
+      list(APPEND temp_list "&&")
+    endif()
+    # Add the patch command to the list
+    list(APPEND temp_list "${PATCH_EXECUTABLE}" "-p1" "<" "${PATCH_FILE}")
+  endforeach()
+
+  # Move temp out into parent scope.
+  set(CPM_ARGS_UNPARSED_ARGUMENTS
+      ${temp_list}
+      PARENT_SCOPE
+  )
+
+endfunction()
+
 # method to overwrite internal FetchContent properties, to allow using CPM.cmake to overload
 # FetchContent calls. As these are internal cmake properties, this method should be used carefully
 # and may need modification in future CMake versions. Source:
@@ -515,14 +648,6 @@ endfunction()
 function(CPMAddPackage)
   cpm_set_policies()
 
-  list(LENGTH ARGN argnLength)
-  if(argnLength EQUAL 1)
-    cpm_parse_add_package_single_arg("${ARGN}" ARGN)
-
-    # The shorthand syntax implies EXCLUDE_FROM_ALL and SYSTEM
-    set(ARGN "${ARGN};EXCLUDE_FROM_ALL;YES;SYSTEM;YES;")
-  endif()
-
   set(oneValueArgs
       NAME
       FORCE
@@ -540,14 +665,31 @@ function(CPMAddPackage)
       GIT_SHALLOW
       EXCLUDE_FROM_ALL
       SOURCE_SUBDIR
+      CUSTOM_CACHE_KEY
   )
 
-  set(multiValueArgs URL OPTIONS DOWNLOAD_COMMAND)
+  set(multiValueArgs URL OPTIONS DOWNLOAD_COMMAND PATCHES)
+
+  list(LENGTH ARGN argnLength)
+
+  # Parse single shorthand argument
+  if(argnLength EQUAL 1)
+    cpm_parse_add_package_single_arg("${ARGN}" ARGN)
+
+    # The shorthand syntax implies EXCLUDE_FROM_ALL and SYSTEM
+    set(ARGN "${ARGN};EXCLUDE_FROM_ALL;YES;SYSTEM;YES;")
+
+    # Parse URI shorthand argument
+  elseif(argnLength GREATER 1 AND "${ARGV0}" STREQUAL "URI")
+    list(REMOVE_AT ARGN 0 1) # remove "URI gh:<...>@version#tag"
+    cpm_parse_add_package_single_arg("${ARGV1}" ARGV0)
+
+    set(ARGN "${ARGV0};EXCLUDE_FROM_ALL;YES;SYSTEM;YES;${ARGN}")
+  endif()
 
   cmake_parse_arguments(CPM_ARGS "" "${oneValueArgs}" "${multiValueArgs}" "${ARGN}")
 
   # Set default values for arguments
-
   if(NOT DEFINED CPM_ARGS_VERSION)
     if(DEFINED CPM_ARGS_GIT_TAG)
       cpm_get_version_from_git_tag("${CPM_ARGS_GIT_TAG}" CPM_ARGS_VERSION)
@@ -633,6 +775,7 @@ function(CPMAddPackage)
       SOURCE_DIR "${PACKAGE_SOURCE}"
       EXCLUDE_FROM_ALL "${CPM_ARGS_EXCLUDE_FROM_ALL}"
       SYSTEM "${CPM_ARGS_SYSTEM}"
+      PATCHES "${CPM_ARGS_PATCHES}"
       OPTIONS "${CPM_ARGS_OPTIONS}"
       SOURCE_SUBDIR "${CPM_ARGS_SOURCE_SUBDIR}"
       DOWNLOAD_ONLY "${DOWNLOAD_ONLY}"
@@ -688,6 +831,8 @@ function(CPMAddPackage)
     set(CPM_FETCHCONTENT_BASE_DIR ${CMAKE_BINARY_DIR}/_deps)
   endif()
 
+  cpm_add_patches(${CPM_ARGS_PATCHES})
+
   if(DEFINED CPM_ARGS_DOWNLOAD_COMMAND)
     list(APPEND CPM_ARGS_UNPARSED_ARGUMENTS DOWNLOAD_COMMAND ${CPM_ARGS_DOWNLOAD_COMMAND})
   elseif(DEFINED CPM_ARGS_SOURCE_DIR)
@@ -710,11 +855,24 @@ 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")
+      cpm_get_shortest_hash(
+        "${CPM_SOURCE_CACHE}/${lower_case_name}" # source cache directory
+        "${origin_hash}" # Input hash
+        origin_hash # Computed hash
+      )
       set(download_directory ${CPM_SOURCE_CACHE}/${lower_case_name}/${origin_hash}/${CPM_ARGS_NAME})
     else()
       string(SHA1 origin_hash "${origin_parameters}")
+      cpm_get_shortest_hash(
+        "${CPM_SOURCE_CACHE}/${lower_case_name}" # source cache directory
+        "${origin_hash}" # Input hash
+        origin_hash # Computed hash
+      )
       set(download_directory ${CPM_SOURCE_CACHE}/${lower_case_name}/${origin_hash})
     endif()
     # Expand `download_directory` relative path. This is important because EXISTS doesn't work for
@@ -781,7 +939,9 @@ function(CPMAddPackage)
     endif()
   endif()
 
-  cpm_create_module_file(${CPM_ARGS_NAME} "CPMAddPackage(\"${ARGN}\")")
+  if(NOT "${DOWNLOAD_ONLY}")
+    cpm_create_module_file(${CPM_ARGS_NAME} "CPMAddPackage(\"${ARGN}\")")
+  endif()
 
   if(CPM_PACKAGE_LOCK_ENABLED)
     if((CPM_ARGS_VERSION AND NOT CPM_ARGS_SOURCE_DIR) OR CPM_INCLUDE_ALL_IN_PACKAGE_LOCK)
@@ -798,14 +958,39 @@ function(CPMAddPackage)
   )
 
   if(NOT CPM_SKIP_FETCH)
+    # CMake 3.28 added EXCLUDE, SYSTEM (3.25), and SOURCE_SUBDIR (3.18) to FetchContent_Declare.
+    # Calling FetchContent_MakeAvailable will then internally forward these options to
+    # add_subdirectory. Up until these changes, we had to call FetchContent_Populate and
+    # add_subdirectory separately, which is no longer necessary and has been deprecated as of 3.30.
+    # A Bug in CMake prevents us to use the non-deprecated functions until 3.30.3.
+    set(fetchContentDeclareExtraArgs "")
+    if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.30.3")
+      if(${CPM_ARGS_EXCLUDE_FROM_ALL})
+        list(APPEND fetchContentDeclareExtraArgs EXCLUDE_FROM_ALL)
+      endif()
+      if(${CPM_ARGS_SYSTEM})
+        list(APPEND fetchContentDeclareExtraArgs SYSTEM)
+      endif()
+      if(DEFINED CPM_ARGS_SOURCE_SUBDIR)
+        list(APPEND fetchContentDeclareExtraArgs SOURCE_SUBDIR ${CPM_ARGS_SOURCE_SUBDIR})
+      endif()
+      # For CMake version <3.28 OPTIONS are parsed in cpm_add_subdirectory
+      if(CPM_ARGS_OPTIONS AND NOT DOWNLOAD_ONLY)
+        foreach(OPTION ${CPM_ARGS_OPTIONS})
+          cpm_parse_option("${OPTION}")
+          set(${OPTION_KEY} "${OPTION_VALUE}")
+        endforeach()
+      endif()
+    endif()
     cpm_declare_fetch(
-      "${CPM_ARGS_NAME}" "${CPM_ARGS_VERSION}" "${PACKAGE_INFO}" "${CPM_ARGS_UNPARSED_ARGUMENTS}"
+      "${CPM_ARGS_NAME}" ${fetchContentDeclareExtraArgs} "${CPM_ARGS_UNPARSED_ARGUMENTS}"
     )
-    cpm_fetch_package("${CPM_ARGS_NAME}" populated)
+
+    cpm_fetch_package("${CPM_ARGS_NAME}" ${DOWNLOAD_ONLY} populated ${CPM_ARGS_UNPARSED_ARGUMENTS})
     if(CPM_SOURCE_CACHE AND download_directory)
       file(LOCK ${download_directory}/../cmake.lock RELEASE)
     endif()
-    if(${populated})
+    if(${populated} AND ${CMAKE_VERSION} VERSION_LESS "3.30.3")
       cpm_add_subdirectory(
         "${CPM_ARGS_NAME}"
         "${DOWNLOAD_ONLY}"
@@ -916,7 +1101,7 @@ function(CPMGetPackageVersion PACKAGE OUTPUT)
 endfunction()
 
 # declares a package in FetchContent_Declare
-function(cpm_declare_fetch PACKAGE VERSION INFO)
+function(cpm_declare_fetch PACKAGE)
   if(${CPM_DRY_RUN})
     cpm_message(STATUS "${CPM_INDENT} Package not declared (dry run)")
     return()
@@ -992,7 +1177,7 @@ endfunction()
 
 # downloads a previously declared package via FetchContent and exports the variables
 # `${PACKAGE}_SOURCE_DIR` and `${PACKAGE}_BINARY_DIR` to the parent scope
-function(cpm_fetch_package PACKAGE populated)
+function(cpm_fetch_package PACKAGE DOWNLOAD_ONLY populated)
   set(${populated}
       FALSE
       PARENT_SCOPE
@@ -1007,7 +1192,24 @@ function(cpm_fetch_package PACKAGE populated)
   string(TOLOWER "${PACKAGE}" lower_case_name)
 
   if(NOT ${lower_case_name}_POPULATED)
-    FetchContent_Populate(${PACKAGE})
+    if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.30.3")
+      if(DOWNLOAD_ONLY)
+        # MakeAvailable will call add_subdirectory internally which is not what we want when
+        # DOWNLOAD_ONLY is set. Populate will only download the dependency without adding it to the
+        # build
+        FetchContent_Populate(
+          ${PACKAGE}
+          SOURCE_DIR "${CPM_FETCHCONTENT_BASE_DIR}/${lower_case_name}-src"
+          BINARY_DIR "${CPM_FETCHCONTENT_BASE_DIR}/${lower_case_name}-build"
+          SUBBUILD_DIR "${CPM_FETCHCONTENT_BASE_DIR}/${lower_case_name}-subbuild"
+          ${ARGN}
+        )
+      else()
+        FetchContent_MakeAvailable(${PACKAGE})
+      endif()
+    else()
+      FetchContent_Populate(${PACKAGE})
+    endif()
     set(${populated}
         TRUE
         PARENT_SCOPE

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()
@@ -79,3 +79,16 @@ function(ASSERT_NOT_EXISTS file)
     message(FATAL_ERROR "assertion failed: file ${file} exists")
   endif()
 endfunction()
+
+function(ASSERT_CONTENTS_EQUAL file content)
+  if(EXISTS ${file})
+    file(READ ${file} file_content)
+    if(content STREQUAL file_content)
+      message(STATUS "test passed: '${file}' exists and contains '${content}'")
+    else()
+      message(FATAL_ERROR "assertion failed: file '${file}' does not contain expected content.")
+    endif()
+  else()
+    message(FATAL_ERROR "assertion failed: file '${file} does not exist")
+  endif()
+endfunction()

examples/boost/CMakeLists.txt

@@ -13,9 +13,12 @@ include(../../cmake/CPM.cmake)
 
 CPMAddPackage(
   NAME Boost
-  VERSION 1.81.0
-  GITHUB_REPOSITORY "boostorg/boost"
-  GIT_TAG "boost-1.81.0"
+  VERSION 1.86.0 # Versions less than 1.85.0 may need patches for installation targets.
+  URL https://github.com/boostorg/boost/releases/download/boost-1.86.0/boost-1.86.0-cmake.tar.xz
+  URL_HASH SHA256=2c5ec5edcdff47ff55e27ed9560b0a0b94b07bd07ed9928b476150e16b0efc57
+  OPTIONS "BOOST_ENABLE_CMAKE ON" "BOOST_SKIP_INSTALL_RULES ON" # Set `OFF` for installation
+          "BUILD_SHARED_LIBS OFF" "BOOST_INCLUDE_LIBRARIES container\\\;asio" # Note the escapes!
 )
 
-target_link_libraries(CPMExampleBoost PRIVATE Boost::asio)
+# `Boost::headers` is also valid
+target_link_libraries(CPMExampleBoost PRIVATE Boost::asio Boost::container)

examples/boost/main.cpp

@@ -9,14 +9,22 @@
 //
 
 #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);
 

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/highway/CMakeLists.txt

@@ -0,0 +1,28 @@
+cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
+
+project(CPMExamplePatchHighway)
+
+# ---- Dependencies ----
+
+include(../../cmake/CPM.cmake)
+
+# Google's highway Includes a SIMD sorting function that is faster than x86-simd-sort for larger
+# arrays. See: https://github.com/google/highway/blob/master/g3doc/quick_reference.md
+CPMAddPackage(
+  NAME highway
+  URL https://github.com/google/highway/archive/refs/tags/1.1.0.tar.gz
+  URL_HASH SHA256=354a8b4539b588e70b98ec70844273e3f2741302c4c377bcc4e81b3d1866f7c9
+  PATCHES "highway.patch" # This adds SYSTEM to the includes.
+  OPTIONS "HWY_ENABLE_EXAMPLES OFF" "HWY_ENABLE_INSTALL OFF" "HWY_ENABLE_TESTS OFF"
+)
+
+# ---- Executable ----
+
+if(LINUX)
+  # This would cause a float compare error inside the highway header code if the patch is NOT
+  # applied.
+  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wfloat-equal")
+endif()
+
+add_executable(CPMExamplePatchHighway "main.cpp")
+target_link_libraries(CPMExamplePatchHighway hwy hwy_contrib)

examples/highway/highway.patch

@@ -0,0 +1,28 @@
+Common subdirectories: a/.bcr and b/.bcr
+Common subdirectories: a/.github and b/.github
+diff -u a/CMakeLists.txt b/CMakeLists.txt
+--- a/CMakeLists.txt	2024-05-21 12:50:37.738318520 -0500
++++ b/CMakeLists.txt	2024-05-21 12:49:59.914226871 -0500
+@@ -350,7 +350,7 @@
+ target_compile_options(hwy PRIVATE ${HWY_FLAGS})
+ set_property(TARGET hwy PROPERTY POSITION_INDEPENDENT_CODE ON)
+ set_target_properties(hwy PROPERTIES VERSION ${LIBRARY_VERSION} SOVERSION ${LIBRARY_SOVERSION})
+-target_include_directories(hwy PUBLIC
++target_include_directories(hwy SYSTEM PUBLIC
+     $<BUILD_INTERFACE:${CMAKE_CURRENT_LIST_DIR}>
+     $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>)
+ target_compile_features(hwy PUBLIC cxx_std_11)
+@@ -370,7 +370,7 @@
+ target_compile_options(hwy_contrib PRIVATE ${HWY_FLAGS})
+ set_property(TARGET hwy_contrib PROPERTY POSITION_INDEPENDENT_CODE ON)
+ set_target_properties(hwy_contrib PROPERTIES VERSION ${LIBRARY_VERSION} SOVERSION ${LIBRARY_SOVERSION})
+-target_include_directories(hwy_contrib PUBLIC
++target_include_directories(hwy_contrib SYSTEM PUBLIC
+     $<BUILD_INTERFACE:${CMAKE_CURRENT_LIST_DIR}>
+     $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>)
+ target_compile_features(hwy_contrib PUBLIC cxx_std_11)
+Common subdirectories: a/cmake and b/cmake
+Common subdirectories: a/debian and b/debian
+Common subdirectories: a/docs and b/docs
+Common subdirectories: a/g3doc and b/g3doc
+Common subdirectories: a/hwy and b/hwy

examples/highway/main.cpp

@@ -0,0 +1,27 @@
+#include <hwy/contrib/sort/vqsort.h>  // hwy::VQSort() for large data sets
+
+#include <cstdint>
+#include <random>
+#include <vector>
+
+// Use hwy::VQSort to sort larger vectors
+inline void sort_large(std::vector<double>& v) {
+  hwy::VQSort(v.data(), v.size(), hwy::SortAscending{});
+}
+
+int main(int, char**) {
+  std::random_device random_device;
+  std::default_random_engine random_engine(random_device());
+  std::uniform_real_distribution<double> uniform_dist(0.0, 100.0);
+
+  const std::size_t sz = 100000;
+  std::vector<double> v;
+  v.reserve(sz);
+  for (std::size_t i = 0; i < sz; ++i) {
+    v.push_back(uniform_dist(random_engine));
+  }
+
+  sort_large(v);
+
+  return 0;
+}

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/sol2/CMakeLists.txt

@@ -8,7 +8,7 @@ include(../../cmake/CPM.cmake)
 
 CPMAddPackage(
   NAME lua
-  GIT_REPOSITORY https://github.com/lua/lua.git
+  GITHUB_REPOSITORY lua/lua
   VERSION 5.3.5
   DOWNLOAD_ONLY YES
 )
@@ -21,7 +21,13 @@ if(lua_ADDED)
   target_include_directories(lua SYSTEM PUBLIC $<BUILD_INTERFACE:${lua_SOURCE_DIR}>)
 endif()
 
-CPMAddPackage("gh:ThePhD/sol2@3.3.0")
+CPMAddPackage(
+  NAME sol2
+  GITHUB_REPOSITORY ThePhD/sol2
+  VERSION 3.3.0
+  # fix for clang 18.1.0, see https://github.com/ThePhD/sol2/issues/1581#issuecomment-2103463524
+  PATCHES fix_for_clang.patch
+)
 
 # ---- Executable ----
 

examples/sol2/fix_for_clang.patch

@@ -0,0 +1,18 @@
+diff -u a/include/sol/function_types_stateless.hpp b/include/types/function_types_stateless.hpp
+--- a/include/sol/function_types_stateless.hpp
++++ b/include/sol/function_types_stateless.hpp
+@@ -322,7 +322,13 @@ namespace sol { namespace function_detail {
+ 		}
+ 
+ 		template <bool is_yielding, bool no_trampoline>
+-		static int call(lua_State* L) noexcept(std::is_nothrow_copy_assignable_v<T>) {
++		static int call(lua_State* L)
++#if SOL_IS_ON(SOL_COMPILER_CLANG)
++		// apparent regression in clang 18 - llvm/llvm-project#91362
++#else
++			noexcept(std::is_nothrow_copy_assignable_v<T>)
++#endif
++		{
+ 			int nr;
+ 			if constexpr (no_trampoline) {
+ 				nr = real_call(L);

examples/spdlog/CMakeLists.txt

@@ -9,7 +9,7 @@ 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 re-use fmt from CPM.cmake like this:
+# can let spdlog reuse fmt from CPM.cmake like this:
 #
 # cmake-format: off
 #

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

test/integration/templates/using-patch-adder/lists.in.cmake

@@ -0,0 +1,13 @@
+cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
+
+project(using-patch-adder)
+
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
+
+include("%{cpm_path}")
+
+%{packages}
+
+add_executable(using-patch-adder using-patch-adder.cpp)
+
+target_link_libraries(using-patch-adder adder)

test/integration/templates/using-patch-adder/patches/001-test_patches_command.patch

@@ -0,0 +1,12 @@
+diff --git a/code/adder/adder.hpp b/code/adder/adder.hpp
+index fdb9324..7c2fa00 100644
+--- a/code/adder/adder.hpp
++++ b/code/adder/adder.hpp
+@@ -1,6 +1,6 @@
+ #pragma once
+ 
+-namespace adder
++namespace patched
+ {
+ int add(int a, int b);
+ }

test/integration/templates/using-patch-adder/patches/002-test_patches_command.patch

@@ -0,0 +1,12 @@
+diff --git a/code/adder/adder.cpp b/code/adder/adder.cpp
+index fc6e767..44b1197 100644
+--- a/code/adder/adder.cpp
++++ b/code/adder/adder.cpp
+@@ -1,6 +1,6 @@
+ #include "adder.hpp"
+ 
+-namespace adder
++namespace patched
+ {
+ int add(int a, int b)
+ {

test/integration/templates/using-patch-adder/using-patch-adder.cpp

@@ -0,0 +1,8 @@
+#include <adder/adder.hpp>
+#include <cstdio>
+
+int main() {
+  int sum = patched::add(5, 3);
+  std::printf("%d\n", sum);
+  return 0;
+}

test/integration/test_basics.rb

@@ -31,7 +31,9 @@ class Basics < IntegrationTest
     assert_same_path File.join(prj.bin_dir, 'cpm-package-lock.cmake'), check_and_get('CPM_PACKAGE_LOCK_FILE')
 
     assert_equal 'OFF', check_and_get('CPM_DONT_UPDATE_MODULE_PATH', 'BOOL')
-    assert_same_path File.join(prj.bin_dir, 'CPM_modules'), check_and_get('CPM_MODULE_PATH')
+    if @cache.entries['CMAKE_FIND_PACKAGE_REDIRECTS_DIR'].nil?
+      assert_same_path File.join(prj.bin_dir, 'CPM_modules'), check_and_get('CPM_MODULE_PATH')
+    end
   end
 
   # Test when env CPM_SOURCE_CACHE is set

test/integration/test_patches_command.rb

@@ -0,0 +1,27 @@
+require_relative './lib'
+
+# Tests using a multi-argumenet PATCHES command to fetch and modify a dependency
+
+class DownloadCommand < IntegrationTest
+
+  def test_fetch_dependency_using_download_command
+    prj = make_project from_template: 'using-patch-adder'
+
+    prj.create_lists_from_default_template package: <<~PACK
+      set(DOWNLOAD_DIR ${CMAKE_BINARY_DIR}/_deps/testpack-adder-src)
+      CPMAddPackage(
+        NAME testpack-adder
+        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" "ADDER_BUILD_EXAMPLES OFF"
+        PATCHES
+          patches/001-test_patches_command.patch
+          patches/002-test_patches_command.patch
+      )
+    PACK
+
+    # configure with unpopulated cache
+    assert_success prj.configure
+    assert_success prj.build
+  end
+
+end

test/integration/test_shorthand_syntax.rb

@@ -0,0 +1,86 @@
+require_relative './lib'
+
+class TestShorthandSyntax < IntegrationTest
+
+  def get_project_binaries prj
+    exe_dir = File.join(prj.bin_dir, 'bin')
+    assert File.directory? exe_dir
+    return Dir[exe_dir + '/**/*'].filter {
+        # on multi-configuration generators (like Visual Studio) the executables will be in bin/<Config>
+        # 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)
+        File.basename(_1, '.exe')
+      }.sort
+  end
+
+  def test_create_with_commit_sha
+    prj = make_project from_template: 'using-adder'
+    prj.create_lists_from_default_template package:
+    'CPMAddPackage("gh:cpm-cmake/testpack-adder#cad1cd4b4cdf957c5b59e30bc9a1dd200dbfc716")'
+    assert_success prj.configure
+
+    cache = prj.read_cache
+    assert_equal 1, cache.packages.size
+    assert_equal '0', cache.packages['testpack-adder'].ver
+
+    assert_success prj.build
+    exes = get_project_binaries prj
+    # No adder projects were built as EXCLUDE_FROM_ALL is implicitly set
+    assert_equal ['using-adder'], exes
+  end
+
+  def test_create_with_version
+    prj = make_project from_template: 'using-adder'
+    prj.create_lists_from_default_template package:
+    'CPMAddPackage("gh:cpm-cmake/testpack-adder@1.0.0")'
+    assert_success prj.configure
+
+    cache = prj.read_cache
+    assert_equal 1, cache.packages.size
+    assert_equal '1.0.0', cache.packages['testpack-adder'].ver
+
+    assert_success prj.build
+    exes = get_project_binaries prj
+    assert_equal ['using-adder'], exes
+  end
+
+  def test_create_with_all
+    prj = make_project from_template: 'using-adder'
+    prj.create_lists_from_default_template package:
+    'CPMAddPackage(
+      URI "gh:cpm-cmake/testpack-adder@1.0.0"
+      EXCLUDE_FROM_ALL false
+    )'
+    assert_success prj.configure
+
+    cache = prj.read_cache
+    assert_equal cache.packages.size, 1
+    assert_equal cache.packages['testpack-adder'].ver, '1.0.0'
+    
+    assert_success prj.build
+    exes = get_project_binaries prj
+    assert_equal exes, ['simple', 'test-adding', 'using-adder']
+  end
+
+  def test_create_with_tests_but_without_examples
+    prj = make_project from_template: 'using-adder'
+    prj.create_lists_from_default_template package:
+    'CPMAddPackage(
+      URI "gh:cpm-cmake/testpack-adder@1.0.0"
+      OPTIONS "ADDER_BUILD_EXAMPLES OFF" "ADDER_BUILD_TESTS TRUE"
+      EXCLUDE_FROM_ALL false
+    )'
+    assert_success prj.configure
+
+    cache = prj.read_cache
+    assert_equal cache.packages.size, 1
+    assert_equal cache.packages['testpack-adder'].ver, '1.0.0'
+    
+    assert_success prj.build
+    exes = get_project_binaries prj
+    assert_equal exes, ['test-adding', 'using-adder']
+  end
+
+end

test/integration/test_simple.rb

@@ -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

@@ -75,6 +75,17 @@ class SourceCache < IntegrationTest
     assert_equal ver, package.ver
     expected_parent_dir = File.join(@cache_dir, name.downcase)
     assert package.src_dir.start_with?(expected_parent_dir), "#{package.src_dir} must be in #{expected_parent_dir}"
-    assert_equal dir_sha1, File.basename(package.src_dir)
+
+    # The hash has been shortened by cpm_get_shortest_hash. The following
+    # should hold:
+    # - The short hash should be a prefix of the input hash
+    # - There should be a file ".../${short_hash}.hash" which matches the full hash
+    short_hash = File.basename(package.src_dir)
+    assert dir_sha1.start_with?(short_hash), "short_hash should be a prefix of dir_sha1"
+
+    # Check that the full hash is stored in the .hash file
+    hash_file = "#{package.src_dir}.hash"
+    assert File.exist?(hash_file), "Hash file #{hash_file} should exist"
+    assert_equal dir_sha1, File.read(hash_file), "Hash file should contain the full original hash"
   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

@@ -137,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")

test/unit/get_shortest_hash.cmake

@@ -0,0 +1,93 @@
+cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
+
+include(${CPM_PATH}/CPM.cmake)
+include(${CPM_PATH}/testing.cmake)
+
+# Random suffix
+string(
+  RANDOM
+  LENGTH 6
+  ALPHABET "0123456789abcdef" tmpdir_suffix
+)
+
+# Seconds since epoch
+string(TIMESTAMP tmpdir_base "%s" UTC)
+
+set(tmp "${CMAKE_CURRENT_BINARY_DIR}/get_shortest_hash-${tmpdir_base}-${tmpdir_suffix}")
+
+if(IS_DIRECTORY ${tmp})
+  message(FATAL_ERROR "Test directory ${tmp} already exists")
+endif()
+
+file(MAKE_DIRECTORY "${tmp}")
+
+# 1. Sanity check: none of these directories should exist yet
+
+assert_not_exists(${tmp}/cccb.hash)
+assert_not_exists(${tmp}/cccb77ae.hash)
+assert_not_exists(${tmp}/cccb77ae9609.hash)
+assert_not_exists(${tmp}/cccb77ae9608.hash)
+assert_not_exists(${tmp}/cccb77be.hash)
+
+# 1. The directory is empty, so it should get a 4-character hash
+cpm_get_shortest_hash(${tmp} "cccb77ae9609d2768ed80dd42cec54f77b1f1455" hash)
+assert_equal(${hash} "cccb")
+assert_contents_equal(${tmp}/cccb.hash cccb77ae9609d2768ed80dd42cec54f77b1f1455)
+
+# 1. Calling the function with a new hash that differs subtly should result in more characters being
+#   used, enough to uniquely identify the hash
+
+cpm_get_shortest_hash(${tmp} "cccb77ae9609d2768ed80dd42cec54f77b1f1456" hash)
+assert_equal(${hash} "cccb77ae")
+assert_contents_equal(${tmp}/cccb77ae.hash cccb77ae9609d2768ed80dd42cec54f77b1f1456)
+
+cpm_get_shortest_hash(${tmp} "cccb77ae9609d2768ed80dd42cec54f77b1f1457" hash)
+assert_equal(${hash} "cccb77ae9609")
+assert_contents_equal(${tmp}/cccb77ae9609.hash cccb77ae9609d2768ed80dd42cec54f77b1f1457)
+
+cpm_get_shortest_hash(${tmp} "cccb77ae9608d2768ed80dd42cec54f77b1f1455" hash)
+assert_equal(${hash} "cccb77ae9608")
+assert_contents_equal(${tmp}/cccb77ae9608.hash cccb77ae9608d2768ed80dd42cec54f77b1f1455)
+
+cpm_get_shortest_hash(${tmp} "cccb77be9609d2768ed80dd42cec54f77b1f1456" hash)
+assert_equal(${hash} "cccb77be")
+assert_contents_equal(${tmp}/cccb77be.hash cccb77be9609d2768ed80dd42cec54f77b1f1456)
+
+# check that legacy hashs are recognized
+file(MAKE_DIRECTORY "${tmp}/cccb77be9609d2768ed80dd42cec54f77b1f1457")
+cpm_get_shortest_hash(${tmp} "cccb77be9609d2768ed80dd42cec54f77b1f1457" hash)
+assert_equal(${hash} "cccb77be9609d2768ed80dd42cec54f77b1f1457")
+
+# 1. The old file should still exist, and have the same content
+assert_contents_equal(${tmp}/cccb.hash cccb77ae9609d2768ed80dd42cec54f77b1f1455)
+assert_contents_equal(${tmp}/cccb77ae.hash cccb77ae9609d2768ed80dd42cec54f77b1f1456)
+assert_contents_equal(${tmp}/cccb77ae9609.hash cccb77ae9609d2768ed80dd42cec54f77b1f1457)
+assert_contents_equal(${tmp}/cccb77ae9608.hash cccb77ae9608d2768ed80dd42cec54f77b1f1455)
+assert_contents_equal(${tmp}/cccb77be.hash cccb77be9609d2768ed80dd42cec54f77b1f1456)
+
+# 1. Confirm idempotence: calling any of these function should produce the same hash as before (hash
+#   lookups work correctly once the .hash files are created)
+
+cpm_get_shortest_hash(${tmp} "cccb77ae9609d2768ed80dd42cec54f77b1f1455" hash)
+assert_equal(${hash} "cccb")
+assert_contents_equal(${tmp}/cccb.hash cccb77ae9609d2768ed80dd42cec54f77b1f1455)
+
+cpm_get_shortest_hash(${tmp} "cccb77ae9609d2768ed80dd42cec54f77b1f1456" hash)
+assert_equal(${hash} "cccb77ae")
+assert_contents_equal(${tmp}/cccb77ae.hash cccb77ae9609d2768ed80dd42cec54f77b1f1456)
+
+cpm_get_shortest_hash(${tmp} "cccb77ae9609d2768ed80dd42cec54f77b1f1457" hash)
+assert_equal(${hash} "cccb77ae9609")
+assert_contents_equal(${tmp}/cccb77ae9609.hash cccb77ae9609d2768ed80dd42cec54f77b1f1457)
+
+cpm_get_shortest_hash(${tmp} "cccb77ae9608d2768ed80dd42cec54f77b1f1455" hash)
+assert_equal(${hash} "cccb77ae9608")
+assert_contents_equal(${tmp}/cccb77ae9608.hash cccb77ae9608d2768ed80dd42cec54f77b1f1455)
+
+cpm_get_shortest_hash(${tmp} "cccb77be9609d2768ed80dd42cec54f77b1f1456" hash)
+assert_equal(${hash} "cccb77be")
+assert_contents_equal(${tmp}/cccb77be.hash cccb77be9609d2768ed80dd42cec54f77b1f1456)
+
+# 1. Cleanup - remove the temporary directory that we created
+
+file(REMOVE_RECURSE ${tmp})

test/unit/local_dependency/ModuleCMakeLists.txt.in

@@ -8,6 +8,10 @@ option(ENABLE_TEST_COVERAGE "Enable test coverage" OFF)
 
 # ---- Dependencies ----
 
+if (@TEST_FORCE_MODULE_MODE@)
+  unset(CMAKE_FIND_PACKAGE_REDIRECTS_DIR CACHE)
+endif()
+
 include(@CPM_PATH@/CPM.cmake)
 
 CPMAddPackage(
@@ -15,21 +19,23 @@ CPMAddPackage(
   SOURCE_DIR ${CMAKE_CURRENT_LIST_DIR}/dependency
 )
 
-# ---- check if generated modules override find_package ----
-
-if (@test_check_find_package@)
-  find_package(@TEST_DEPENDENCY_NAME@ REQUIRED)
-endif()
-
 # ---- Call dependency method to validate correct addition of directory ----
 
 dependency_function()
 
-# ---- Check parameters ----
-
+# ---- Check newly added ----
 include(@CPM_PATH@/testing.cmake)
-
 ASSERT_TRUTHY(@TEST_DEPENDENCY_NAME@_ADDED)
+
+# ---- Check if generated modules override find_package ----
+
+if (@TEST_FIND_PACKAGE@)
+  find_package(@TEST_DEPENDENCY_NAME@ @TEST_FIND_PACKAGE_CONFIG@ REQUIRED)
+  find_package(@TEST_CANT_FIND_PACKAGE_NAME@ @TEST_FIND_PACKAGE_CONFIG@ QUIET)
+  ASSERT_FALSY(@TEST_CANT_FIND_PACKAGE_NAME@_FOUND)
+endif()
+
+# ---- Check parameters ----
 ASSERT_DEFINED(@TEST_DEPENDENCY_NAME@_SOURCE_DIR)
 ASSERT_DEFINED(@TEST_DEPENDENCY_NAME@_BINARY_DIR)
 ASSERT_EQUAL("${CPM_LAST_PACKAGE_NAME}" "@TEST_DEPENDENCY_NAME@")

test/unit/modules.cmake

@@ -3,7 +3,8 @@ include(${CPM_PATH}/testing.cmake)
 
 set(TEST_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/modules)
 
-function(init_project_with_dependency TEST_DEPENDENCY_NAME)
+function(init_project_with_dependency TEST_DEPENDENCY_NAME TEST_CANT_FIND_PACKAGE_NAME)
+  set(TEST_FIND_PACKAGE ON)
   configure_package_config_file(
     "${CMAKE_CURRENT_LIST_DIR}/local_dependency/ModuleCMakeLists.txt.in"
     "${CMAKE_CURRENT_LIST_DIR}/local_dependency/CMakeLists.txt"
@@ -18,11 +19,17 @@ function(init_project_with_dependency TEST_DEPENDENCY_NAME)
   assert_equal(${ret} "0")
 endfunction()
 
-init_project_with_dependency(A)
-assert_exists(${TEST_BUILD_DIR}/CPM_modules)
-assert_exists(${TEST_BUILD_DIR}/CPM_modules/FindA.cmake)
-assert_not_exists(${TEST_BUILD_DIR}/CPM_modules/FindB.cmake)
+init_project_with_dependency(A B)
+init_project_with_dependency(B A)
 
-init_project_with_dependency(B)
-assert_not_exists(${TEST_BUILD_DIR}/CPM_modules/FindA.cmake)
-assert_exists(${TEST_BUILD_DIR}/CPM_modules/FindB.cmake)
+if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.24.0")
+  set(TEST_FIND_PACKAGE_CONFIG CONFIG)
+  init_project_with_dependency(A B)
+  init_project_with_dependency(B A)
+
+  # Test the fallback path for CMake <3.24 works
+  set(TEST_FIND_PACKAGE_CONFIG)
+  set(TEST_FORCE_MODULE_MODE ON)
+  init_project_with_dependency(A B)
+  init_project_with_dependency(B A)
+endif()