Use the GitHub .zip URI instead of GIT_REPOSITORY and GIT_BRANCH (

#257)

This PR uses the GitHub `.zip` URI instead of `GIT_REPOSITORY` and `GIT_BRANCH` so `rapids-cmake` can be loaded on machines that don't have git installed. It might also be good to set [`CMP0135`](https://cmake.org/cmake/help/latest/policy/CMP0135.html) in `RAPIDS.cmake`.

Authors:
  - Paul Taylor (https:/trxcllnt)

Approvers:
  - Robert Maynard (https:/robertmaynard)
  - Bradley Dice (https:/bdice)

URL: #257

RAPIDS.cmake

@@ -17,13 +17,50 @@
 # This is the preferred entry point for projects using rapids-cmake
 #
 
-set(rapids-cmake-version 22.10)
+# Allow users to control which version is used
+if(NOT rapids-cmake-version)
+ # Define a default version if the user doesn't set one
+ set(rapids-cmake-version 22.10)
+endif()
+
+# Allow users to control which GitHub repo is fetched
+if(NOT rapids-cmake-repo)
+ # Define a default repo if the user doesn't set one
+ set(rapids-cmake-repo rapidsai/rapids-cmake)
+endif()
+
+# Allow users to control which branch is fetched
+if(NOT rapids-cmake-branch)
+ # Define a default branch if the user doesn't set one
+ set(rapids-cmake-branch "branch-${rapids-cmake-version}")
+endif()
+
+# Allow users to control the exact URL passed to FetchContent
+if(NOT rapids-cmake-url)
+ # Construct a default URL if the user doesn't set one
+ set(rapids-cmake-url "https:/${rapids-cmake-repo}")
+ # In order of specificity
+ if(rapids-cmake-sha)
+ # An exact git SHA takes precedence over anything
+ string(APPEND rapids-cmake-url "archive/${rapids-cmake-sha}.zip")
+ elseif(rapids-cmake-tag)
+ # Followed by a git tag name
+ string(APPEND rapids-cmake-url "archive/refs/tags/${rapids-cmake-tag}.zip")
+ else()
+ # Or if neither of the above two were defined, use a branch
+ string(APPEND rapids-cmake-url "archive/refs/heads/${rapids-cmake-branch}.zip")
+ endif()
+endif()
+
+if(POLICY CMP0135)
+ cmake_policy(PUSH)
+ cmake_policy(SET CMP0135 NEW)
+endif()
 include(FetchContent)
-FetchContent_Declare(
- rapids-cmake
- GIT_REPOSITORY https:/rapidsai/rapids-cmake.git
- GIT_TAG branch-${rapids-cmake-version}
-)
+FetchContent_Declare(rapids-cmake URL "${rapids-cmake-url}")
+if(POLICY CMP0135)
+ cmake_policy(POP)
+endif()
 FetchContent_GetProperties(rapids-cmake)
 if(rapids-cmake_POPULATED)
  # Something else has already populated rapids-cmake, only thing
@@ -34,4 +71,3 @@ if(rapids-cmake_POPULATED)
 else()
  FetchContent_MakeAvailable(rapids-cmake)
 endif()
-

README.md

@@ -110,24 +110,38 @@ The most commonly used function are:
 
 ## Overriding RAPIDS.cmake
 
-At times projects or developers will need to verify ``rapids-cmake`` branches. To do this you need to override the default git repositry and branch that ``RAPIDS.cmake`` downloads, which should be done
-like this:
+At times projects or developers will need to verify ``rapids-cmake`` branches. To do this you can set variables that control which repository ``RAPIDS.cmake`` downloads, which should be done like this:
 
 ```cmake
+ # To override the version that is pulled:
+ set(rapids-cmake-version "<version>")
 
- include(FetchContent)
- FetchContent_Declare(
- rapids-cmake
- GIT_REPOSITORY https:/<my_fork>/rapids-cmake.git
- GIT_TAG <my_feature_branch>
- )
- file(DOWNLOAD https://raw.githubusercontent.com/rapidsai/rapids-cmake/branch-21.12/RAPIDS.cmake
+ # To override the GitHub repository:
+ set(rapids-cmake-repo "<my_fork>")
+
+ # To use an exact Git SHA:
+ set(rapids-cmake-sha "<my_git_sha>")
+
+ # To use a Git tag:
+ set(rapids-cmake-tag "<my_git_tag>")
+
+ # To override the repository branch:
+ set(rapids-cmake-branch "<my_feature_branch>")
+
+ # Or to override the entire repository URL (e.g. to use a GitLab repo):
+ set(rapids-cmake-url "https://gitlab.com/<my_user>/<my_fork>/-/archive/<my_branch>/<my_fork>-<my_branch>.zip")
+
+ file(DOWNLOAD https://raw.githubusercontent.com/rapidsai/rapids-cmake/branch-22.10/RAPIDS.cmake
  ${CMAKE_CURRENT_BINARY_DIR}/RAPIDS.cmake)
  include(${CMAKE_CURRENT_BINARY_DIR}/RAPIDS.cmake)
 ```
 
-This tells ``FetchContent`` to ignore the explicit url and branch in ``RAPIDS.cmake`` and use the
-ones provided.
+A few notes:
+
+- An explicitly defined ``rapids-cmake-url`` will always be used
+- `rapids-cmake-sha` takes precedence over `rapids-cmake-tag`
+- `rapids-cmake-tag` takes precedence over `rapids-cmake-branch`
+- It is advised to always set `rapids-cmake-version` to the version expected by the repo your modifications will pull
 
 ## Contributing
 

docs/basics.rst

@@ -45,7 +45,7 @@ There are two ways projects can use ``rapids-cmake`` functions.
 Overriding RAPIDS.cmake
 ***********************
 
-At times projects or developers will need to verify ``rapids-cmake`` branches. To do this you need to override the default git repositry and branch that ``RAPIDS.cmake`` downloads, which should be done
+At times projects or developers will need to verify ``rapids-cmake`` branches. To do this you need to override the default git repository and branch that ``RAPIDS.cmake`` downloads, which should be done
 like this:
 
 .. code-block:: cmake

rapids-cmake/rapids-version.cmake

@@ -16,4 +16,6 @@
 # can't have an include guard on this file
 # that breaks its usage by cpm/detail/package_details
 
-set(rapids-cmake-version 22.10)
+if(NOT DEFINED rapids-cmake-version)
+ set(rapids-cmake-version 22.10)
+endif()