Introduce rapids_cpm_<preset> (#52)

Requires #48 and #51

Adds rapids_cpm_<PackageName> for common packages

Fixes #32

The following packages are now are easier to user for RAPIDS projects
as rapids-cmake offers a pre-configured setup for each project.

-   GTest
-   NVBench
-   RMM
-   SpdLog
-   Thrust

On top of providing a consistent version of these packages to all RAPIDS projects, rapids-cmake now is able to deduce when these projects should also be installed.

```cmake

rapids_cpm_gtest(BUILD_EXPORT_SET myproject)
rapdis_cpm_rmm(BUILD_EXPORT_SET myproject
               INSTALL_EXPORT_SET myproject)
```
Given the above snippet when RMM is built as a subcomponent of `myproject` it will be installed as well. This is done since
RMM is part of the INSTALL export set, and therefore must be available from an installed version of `myproject`.

Authors:
  - Robert Maynard (https://github.com/robertmaynard)

Approvers:
  - Dante Gama Dessavre (https://github.com/dantegd)

URL: #52

CONTRIBUTING.md

@@ -73,7 +73,7 @@ Please ensure that when you are creating new features you follow the following g
    - Each user facing `.cmake` file should have include guards (`include_guard(GLOBAL)`)
    - Each user facing `.cmake` file should be documented following the rst structure
    - Each user facing function should be added to the `cmake-format.json` document
-    - Run `cmake-annotate --json` on the `.cmake` file as a starting point
+    - Run `cmake-genparsers -f json` on the `.cmake` file as a starting point
    - Each function first line should be `list(APPEND CMAKE_MESSAGE_CONTEXT "rapids.<component>.<function>")`
    - A file should not modify any state simply by being included. State modification should
      only occur inside functions unless absolutely neccessary due to restrctions of the CMake

cmake-format-rapids-cmake.json

@@ -55,6 +55,54 @@
           "nargs": 0
         }
       },
+      "rapids_cpm_gtest": {
+        "pargs": {
+          "nargs": 0
+        },
+        "kwargs": {
+          "BUILD_EXPORT_SET": 1,
+          "INSTALL_EXPORT_SET": 1
+        }
+      },
+
+      "rapids_cpm_nvbench": {
+        "pargs": {
+          "nargs": 0
+        },
+        "kwargs": {
+          "BUILD_EXPORT_SET": 1
+        }
+      },
+
+      "rapids_cpm_rmm": {
+        "pargs": {
+          "nargs": 0
+        },
+        "kwargs": {
+          "BUILD_EXPORT_SET": 1,
+          "INSTALL_EXPORT_SET": 1
+        }
+      },
+
+      "rapids_cpm_spdlog": {
+        "pargs": {
+          "nargs": 0
+        },
+        "kwargs": {
+          "BUILD_EXPORT_SET": 1,
+          "INSTALL_EXPORT_SET": 1
+        }
+      },
+
+      "rapids_cpm_thrust": {
+        "pargs": {
+          "nargs": 2
+        },
+        "kwargs": {
+          "BUILD_EXPORT_SET": 1,
+          "INSTALL_EXPORT_SET": 1
+        }
+      },
 
       "rapids_cuda_init_architectures": {
         "pargs": {

docs/api.rst

@@ -30,6 +30,26 @@ tracking of these dependencies for correct export support.
    /command/rapids_cpm_init
    /command/rapids_cpm_find
 
+CPM Pre-Configured Pacakges
+***************************
+
+These `rapids_cpm` functions allow projects to easily find or build common
+RAPIDS dependencies.
+
+These allow projects to make sure they use the same version and flags for
+dependencies as the rest of RAPIDS. The exact versions that each pre-configured
+package uses :ref:`can be found here. <cpm_versions>`
+
+.. toctree::
+   :titlesonly:
+
+   /packages/rapids_cpm_gtest
+   /packages/rapids_cpm_nvbench
+   /packages/rapids_cpm_rmm
+   /packages/rapids_cpm_spdlog
+   /packages/rapids_cpm_thrust
+
+
 Find
 ****
 

docs/packages/example.json

@@ -0,0 +1,11 @@
+
+{
+  "packages" : {
+    "Thrust" : {
+      "version" : "1.12.0",
+      "git_url" : "https://github.com/NVIDIA/thrust.git",
+      "git_tag" : "${version}",
+      "git_shallow" : true
+    }
+  }
+}

docs/packages/rapids_cpm_gtest.rst

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

docs/packages/rapids_cpm_nvbench.rst

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

docs/packages/rapids_cpm_rmm.rst

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

docs/packages/rapids_cpm_spdlog.rst

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

docs/packages/rapids_cpm_thrust.rst

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

docs/packages/rapids_cpm_versions.rst

@@ -0,0 +1,63 @@
+:orphan:
+
+
+rapids-cmake package version format
+###################################
+
+
+rapids-cmake uses a JSON file to encode the version of a project and how to download the project.
+
+The JSON format is a root object that contains the ``packages`` object.
+
+The ``packages`` object contains a key/value map of all supported
+packages where the key is the case senstive name of the project and
+the value is a ``project`` object, as seen in this example:
+
+.. literalinclude:: /packages/example.json
+  :language: json
+
+
+Project Object Fields
+*********************
+
+Each ``project`` object must contain the following fields so that
+rapids-cmake can properly use CPM to find or download the project
+as needed.
+
+``version``
+
+    A required string representing the version of the project to be used
+    by :cmake:command:`rapids_cpm_find` when looking for a local installed
+    copy of the project.
+
+    Supports the following placeholders:
+        - ``${rapids-cmake-version}`` will be evulated to 'major.minor' of the current rapids-cmake cal-ver value.
+
+``git_url``
+
+    A required string representing the git url to be used when cloning the
+    project locally by the :cmake:command:`rapids_cpm_find` when a locally
+    installed copy of the project can't be found.
+
+``git_tag``
+
+    A required string representing the git tag to be used when cloning the
+    project locally by the :cmake:command:`rapids_cpm_find` when a locally
+    installed copy of the project can't be found.
+
+    Supports the following placeholders:
+        - ``${rapids-cmake-version}`` will be evulated to 'major.minor' of the current rapids-cmake cal-ver value.
+        - ``${version}`` will be evulated to the contents of the ``version`` field.
+
+``git_shallow``
+
+    An optional boolean value that represents if we should do a shallow git clone
+    or not. If no such field exists the default is `git_shallow : true`
+
+rapids-cmake package versions
+#############################
+
+
+.. _cpm_versions:
+.. literalinclude:: /../rapids-cmake/cpm/versions.json
+    :language: json

rapids-cmake/cpm/detail/download.cmake

@@ -0,0 +1,65 @@
+#=============================================================================
+# 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_download
+-------------------
+
+.. versionadded:: v21.10.00
+
+Does the downloading of the `CPM` module
+
+.. code-block:: cmake
+
+  rapids_cpm_download()
+
+The CPM module will be downloaded based on the state of :cmake:variable:`CPM_SOURCE_CACHE` and
+:cmake:variable:`ENV{CPM_SOURCE_CACHE}`.
+
+.. note::
+  Use `rapids_cpm_init` instead of this function, as this is an implementation detail
+  required for proper cpm project exporting in build directories
+
+  This function can't call other rapids-cmake functions, due to the
+  restrictions of `write_dependencies.cmake`
+
+#]=======================================================================]
+function(rapids_cpm_download)
+  list(APPEND CMAKE_MESSAGE_CONTEXT "rapids.cpm.download")
+
+  set(CPM_DOWNLOAD_VERSION 7644c3a40fc7889f8dee53ce21e85dc390b883dc) # 0.32.1
+
+  if(CPM_SOURCE_CACHE)
+    # Expand relative path. This is important if the provided path contains a tilde (~)
+    cmake_path(ABSOLUTE_PATH CPM_SOURCE_CACHE)
+    set(CPM_DOWNLOAD_LOCATION "${CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+  elseif(DEFINED ENV{CPM_SOURCE_CACHE})
+    set(CPM_DOWNLOAD_LOCATION "$ENV{CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+  else()
+    set(CPM_DOWNLOAD_LOCATION "${CMAKE_BINARY_DIR}/cmake/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+  endif()
+
+  if(NOT (EXISTS ${CPM_DOWNLOAD_LOCATION}))
+    message(VERBOSE "Downloading CPM.cmake to ${CPM_DOWNLOAD_LOCATION}")
+    file(DOWNLOAD
+         https://raw.githubusercontent.com/cpm-cmake/CPM.cmake/${CPM_DOWNLOAD_VERSION}/cmake/CPM.cmake
+         ${CPM_DOWNLOAD_LOCATION})
+  endif()
+
+  include(${CPM_DOWNLOAD_LOCATION})
+
+endfunction()

rapids-cmake/cpm/detail/load_preset_versions.cmake

@@ -0,0 +1,60 @@
+#=============================================================================
+# 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_load_preset_versions
+-------------------------------
+
+.. versionadded:: v21.10.00
+
+Establish the `CPM` preset package information for the project.
+
+.. code-block:: cmake
+
+  rapids_cpm_load_preset_versions()
+
+.. note::
+  Will be called by the first invocation of :cmake:command:`rapids_cpm_init` or :cmake:command:`rapids_cpm_<pkg>`.
+
+#]=======================================================================]
+function(rapids_cpm_load_preset_versions)
+  list(APPEND CMAKE_MESSAGE_CONTEXT "rapids.cpm.load_preset_versions")
+
+  # Check if we have been loaded before, if so early terminate
+  get_property(already_loaded GLOBAL PROPERTY rapids_cpm_load_presets SET)
+  if(already_loaded)
+    return()
+  endif()
+  set_property(GLOBAL PROPERTY rapids_cpm_load_presets "ON")
+
+  # Load our json files
+  file(READ "${CMAKE_CURRENT_FUNCTION_LIST_DIR}/../versions.json" 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}_json "${data}")
+  endforeach()
+
+endfunction()

rapids-cmake/cpm/detail/package_details.cmake

@@ -0,0 +1,58 @@
+#=============================================================================
+# 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_details
+--------------------------
+
+. code-block:: cmake
+
+  rapids_cpm_package_details(<package_name> <version_variable> <git_url_variable> <git_tag_variable>)
+
+#]=======================================================================]
+function(rapids_cpm_package_details package_name version_var url_var tag_var shallow_var)
+  list(APPEND CMAKE_MESSAGE_CONTEXT "rapids.cpm.rapids_cpm_package_details")
+
+  include("${rapids-cmake-dir}/cpm/detail/load_preset_versions.cmake")
+  rapids_cpm_load_preset_versions()
+
+  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()
+
+  # Evaluate any magic placeholders in the version or tag components including the
+  # `rapids-cmake-version` value
+  include("${rapids-cmake-dir}/rapids-version.cmake")
+
+  cmake_language(EVAL CODE "set(version ${version})")
+  cmake_language(EVAL CODE "set(git_tag ${git_tag})")
+
+  set(${version_var} ${version} PARENT_SCOPE)
+  set(${url_var} ${git_url} PARENT_SCOPE)
+  set(${tag_var} ${git_tag} PARENT_SCOPE)
+  set(${shallow_var} ${git_shallow} PARENT_SCOPE)
+
+endfunction()

rapids-cmake/cpm/find.cmake

@@ -67,12 +67,17 @@ consistency. List all targets used by your project in `GLOBAL_TARGET`.
 
 ``INSTALL_EXPORT_SET``
   Record a :cmake:command:`find_dependency(<PackageName> ...)` call needs to occur as part of
-  our build directory export set.
+  our install directory export set.
 
 ``CPM_ARGS``
   Required placeholder to be provied before any extra arguments that need to
   be passed down to :cmake:command:`CPMFindPackage`.
 
+Result Variables
+^^^^^^^^^^^^^^^^
+  :cmake:variable:`<PackageName>_SOURCE_DIR` is set to the path to the source directory of <PackageName>.
+  :cmake:variable:`<PackageName>_BINAR_DIR`  is set to the path to the build directory of  <PackageName>.
+  :cmake:variable:`<PackageName>_ADDED`      is set to a true value if <PackageName> has not been added before.
 
 .. note::
   Adding an export set to :cmake:command:`rapids_cpm_find` has different behavior