Adding PATCHES keyword. (#558)

* Adding PATCHES keyword.

* Formatting fix.

* Move cpm_add_patches() outside if/else scopes.

* cmake-format: add PATCHES to CPMAddPackage.

* Integration tests for PATCHES command.

* Use get_filename_component() in place of cmake_path() for use with all cmake versions 3.14 and above.

* Added an example and improved comment for cpm_add_patches.

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;
+}