Allow projects to override version.json information

Fixes #73

Introduces `OVERRIDE` argument to rapids_cpm_init() and the
rapids_cpm_package_override command.

Both of these allow consuming projects to inject new
urls/repository/tag/etc for rapids-cmake cpm pre-configured packages

cmake-format-rapids-cmake.json

@@ -53,8 +53,17 @@
       "rapids_cpm_init": {
         "pargs": {
           "nargs": 0
+        },
+        "kwargs": {
+          "OVERRIDE": 1,
+        }
+      },
+      "rapids_cpm_package_override": {
+        "pargs": {
+          "nargs": 1
         }
       },
+
       "rapids_cpm_gtest": {
         "pargs": {
           "nargs": 0
@@ -64,7 +73,6 @@
           "INSTALL_EXPORT_SET": 1
         }
       },
-
       "rapids_cpm_nvbench": {
         "pargs": {
           "nargs": 0
@@ -73,7 +81,6 @@
           "BUILD_EXPORT_SET": 1
         }
       },
-
       "rapids_cpm_rmm": {
         "pargs": {
           "nargs": 0
@@ -83,7 +90,6 @@
           "INSTALL_EXPORT_SET": 1
         }
       },
-
       "rapids_cpm_spdlog": {
         "pargs": {
           "nargs": 0
@@ -93,7 +99,6 @@
           "INSTALL_EXPORT_SET": 1
         }
       },
-
       "rapids_cpm_thrust": {
         "pargs": {
           "nargs": 2

docs/api.rst

@@ -48,6 +48,8 @@ package uses :ref:`can be found here. <cpm_versions>`
    /packages/rapids_cpm_rmm
    /packages/rapids_cpm_spdlog
    /packages/rapids_cpm_thrust
+   /command/rapids_cpm_package_override
+
 
 
 Find

docs/command/rapids_cpm_package_override.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../../rapids-cmake/cpm/package_override.cmake

docs/packages/rapids_cpm_versions.rst

@@ -1,5 +1,5 @@
 :orphan:
-
+.. _cpm_version_format:
 
 rapids-cmake package version format
 ###################################

rapids-cmake/cpm/detail/package_details.cmake

@@ -30,18 +30,28 @@ function(rapids_cpm_package_details package_name version_var url_var tag_var sha
   include("${rapids-cmake-dir}/cpm/detail/load_preset_versions.cmake")
   rapids_cpm_load_preset_versions()
 
+  get_property(override_json_data GLOBAL PROPERTY rapids_cpm_${package_name}_override_json)
   get_property(json_data GLOBAL PROPERTY rapids_cpm_${package_name}_json)
 
   # Parse required fields
-  string(JSON version GET "${json_data}" version)
-  string(JSON git_url GET "${json_data}" git_url)
-  string(JSON git_tag GET "${json_data}" git_tag)
-
-  # Parse optional fields
-  string(JSON git_shallow ERROR_VARIABLE git_shallow_error GET "${json_data}" git_shallow)
-  if(git_shallow_error)
-    set(git_shallow ON)
-  endif()
+  function(rapids_cpm_json_get_value name)
+    string(JSON value ERROR_VARIABLE have_error GET "${override_json_data}" ${name})
+    if(have_error)
+      string(JSON value ERROR_VARIABLE have_error GET "${json_data}" ${name})
+    endif()
+
+    if(NOT have_error)
+      set(${name} ${value} PARENT_SCOPE)
+    endif()
+  endfunction()
+
+  rapids_cpm_json_get_value(version)
+  rapids_cpm_json_get_value(git_url)
+  rapids_cpm_json_get_value(git_tag)
+
+  # Parse optional fields, set the variable to the 'default' value first
+  set(git_shallow ON)
+  rapids_cpm_json_get_value(git_shallow)
 
   # Evaluate any magic placeholders in the version or tag components including the
   # `rapids-cmake-version` value

rapids-cmake/cpm/init.cmake

@@ -25,7 +25,7 @@ Establish the `CPM` and preset package infrastructure for the project.
 
 .. code-block:: cmake
 
-  rapids_cpm_init()
+  rapids_cpm_init( [OVERRIDE <json_override_file_path> ] )
 
 The CPM module will be downloaded based on the state of :cmake:variable:`CPM_SOURCE_CACHE` and
 :cmake:variable:`ENV{CPM_SOURCE_CACHE}`. This allows multiple nested projects to share the
@@ -39,9 +39,19 @@ in the build tree of the calling project
 function(rapids_cpm_init)
   list(APPEND CMAKE_MESSAGE_CONTEXT "rapids.cpm.init")
 
+  set(options)
+  set(one_value OVERRIDE)
+  set(multi_value)
+  cmake_parse_arguments(RAPIDS "${options}" "${one_value}" "${multi_value}" ${ARGN})
+
   include("${rapids-cmake-dir}/cpm/detail/load_preset_versions.cmake")
   rapids_cpm_load_preset_versions()
 
+  if(RAPIDS_OVERRIDE)
+    include("${rapids-cmake-dir}/cpm/package_override.cmake")
+    rapids_cpm_package_override("${RAPIDS_OVERRIDE}")
+  endif()
+
   include("${rapids-cmake-dir}/cpm/detail/download.cmake")
   rapids_cpm_download()
 

rapids-cmake/cpm/package_override.cmake

@@ -0,0 +1,62 @@
+#=============================================================================
+# Copyright (c) 2021, NVIDIA CORPORATION.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#=============================================================================
+include_guard(GLOBAL)
+
+#[=======================================================================[.rst:
+rapids_cpm_package_override
+---------------------------
+
+.. versionadded:: v21.10.00
+
+Override `CPM` preset package information for the project.
+
+.. code-block:: cmake
+
+  rapids_cpm_package_override(<json_file_path>)
+
+Allows projects to override the default values for any rapids-cmake
+pre-configured cpm package.
+
+The user provided json file must follow the `versions.json` format,
+which is :ref:`documented here<cpm_version_format>`  and shown in the below
+example:
+
+.. literalinclude:: /packages/example.json
+  :language: json
+
+If the override doesn't specify a value or package entry the default
+version will be used.
+
+#]=======================================================================]
+function(rapids_cpm_package_override filepath)
+  list(APPEND CMAKE_MESSAGE_CONTEXT "rapids.cpm.rapids_cpm_package_override")
+
+  file(READ "${filepath}" json_data)
+
+  # Determine all the projects that exist in the json file
+  string(JSON package_count LENGTH "${json_data}" packages)
+  math(EXPR package_count "${package_count} - 1")
+
+  # For each project cache the subset of the json for that project in a global property
+
+  # cmake-lint: disable=E1120
+  foreach(index RANGE ${package_count})
+    string(JSON package_name MEMBER "${json_data}" packages ${index})
+    string(JSON data GET "${json_data}" packages "${package_name}")
+    set_property(GLOBAL PROPERTY rapids_cpm_${package_name}_override_json "${data}")
+  endforeach()
+
+endfunction()

testing/cpm/CMakeLists.txt

@@ -20,6 +20,15 @@ add_cmake_config_test( cpm_find-existing-target )
 add_cmake_config_test( cpm_find-existing-target-to-export-sets )
 add_cmake_config_test( cpm_find-options-escaped )
 
+add_cmake_config_test( cpm_init-bad-override-path.cmake SHOULD_FAIL )
+add_cmake_config_test( cpm_init-override-multiple.cmake )
+add_cmake_config_test( cpm_init-override-simple.cmake )
+
+add_cmake_config_test( cpm_package_override-bad-path.cmake SHOULD_FAIL )
+add_cmake_config_test( cpm_package_override-before-init.cmake )
+add_cmake_config_test( cpm_package_override-multiple.cmake )
+add_cmake_config_test( cpm_package_override-simple.cmake )
+
 add_cmake_config_test( cpm_gtest-export.cmake SERIAL )
 add_cmake_config_test( cpm_gtest-simple.cmake SERIAL )
 

testing/cpm/cpm_init-bad-override-path.cmake

@@ -0,0 +1,19 @@
+#=============================================================================
+# Copyright (c) 2021, NVIDIA CORPORATION.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#=============================================================================
+include(${rapids-cmake-dir}/cpm/init.cmake)
+
+include("${rapids-cmake-testing-dir}/cpm/setup_cpm_cache.cmake")
+rapids_cpm_init(OVERRIDE ${CMAKE_CURRENT_LIST_DIR}/bad_path.cmake)

testing/cpm/cpm_init-override-multiple.cmake

@@ -0,0 +1,64 @@
+#=============================================================================
+# Copyright (c) 2021, NVIDIA CORPORATION.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#=============================================================================
+include(${rapids-cmake-dir}/cpm/init.cmake)
+
+include("${rapids-cmake-testing-dir}/cpm/setup_cpm_cache.cmake")
+
+
+rapids_cpm_init()
+
+# Load the default values for nvbench and GTest projects
+include("${rapids-cmake-dir}/cpm/detail/package_details.cmake")
+rapids_cpm_package_details(nvbench nvbench_version nvbench_repository nvbench_tag nvbench_shallow)
+rapids_cpm_package_details(GTest GTest_version GTest_repository GTest_tag GTest_shallow)
+
+
+# Need to write out an override file
+file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/override.json
+  [=[
+{
+  "packages" : {
+    "nvbench" : {
+      "git_tag" : "my_tag"
+    },
+    "GTest" : {
+      "version" : "2.99"
+    }
+  }
+}
+  ]=])
+
+rapids_cpm_init(OVERRIDE "${CMAKE_CURRENT_BINARY_DIR}/override.json")
+
+# Verify that the override works
+rapids_cpm_package_details(nvbench version repository tag shallow)
+if(NOT version STREQUAL nvbench_version)
+  message(FATAL_ERROR "default version field was removed.")
+endif()
+if(NOT repository STREQUAL nvbench_repository)
+  message(FATAL_ERROR "default repository field was removed.")
+endif()
+if(NOT tag STREQUAL "my_tag")
+  message(FATAL_ERROR "custom git_tag field was ignored. ${tag} found instead of my_url")
+endif()
+
+rapids_cpm_package_details(GTest version repository tag shallow)
+if(NOT version STREQUAL "2.99")
+  message(FATAL_ERROR "custom version field was removed. ${version} was found instead")
+endif()
+if(NOT tag MATCHES "2.99")
+  message(FATAL_ERROR "custom version field not used when computing git_tag value. ${tag} was found instead")
+endif()

testing/cpm/cpm_init-override-simple.cmake

@@ -0,0 +1,49 @@
+#=============================================================================
+# Copyright (c) 2021, NVIDIA CORPORATION.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#=============================================================================
+include(${rapids-cmake-dir}/cpm/init.cmake)
+
+include("${rapids-cmake-testing-dir}/cpm/setup_cpm_cache.cmake")
+
+# Need to write out an override file
+file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/override.json
+  [=[
+{
+  "packages" : {
+    "nvbench" : {
+      "version" : "custom_version",
+      "git_url" : "my_url",
+      "git_tag" : "my_tag"
+    }
+  }
+}
+  ]=])
+
+rapids_cpm_init(OVERRIDE "${CMAKE_CURRENT_BINARY_DIR}/override.json")
+
+# Verify that the override works
+include("${rapids-cmake-dir}/cpm/detail/package_details.cmake")
+rapids_cpm_package_details(nvbench version repository tag shallow)
+
+if(NOT version STREQUAL "custom_version")
+  message(FATAL_ERROR "custom version field was ignored. ${version} found instead of custom_version")
+endif()
+if(NOT repository STREQUAL "my_url")
+  message(FATAL_ERROR "custom git_url field was ignored. ${repository} found instead of my_url")
+endif()
+if(NOT tag STREQUAL "my_tag")
+  message(FATAL_ERROR "custom git_tag field was ignored. ${tag} found instead of my_tag")
+endif()
+

testing/cpm/cpm_package_override-bad-path.cmake

@@ -0,0 +1,20 @@
+#=============================================================================
+# Copyright (c) 2021, NVIDIA CORPORATION.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#=============================================================================
+include(${rapids-cmake-dir}/cpm/init.cmake)
+include(${rapids-cmake-dir}/cpm/package_override.cmake)
+
+rapids_cpm_init()
+rapids_cpm_package_override(${CMAKE_CURRENT_LIST_DIR}/bad_path.cmake)