Add CMake build for C++ and scikit-build infrastructure for Python package installation

.gitattributes

@@ -0,0 +1 @@
+cunumeric/_version.py export-subst

.gitignore

@@ -34,3 +34,10 @@ cunumeric/install_info.py
 /docs/cunumeric/source/api/generated
 /docs/cunumeric/source/comparison/comparison_table.rst.inc
 *.egg-info
+.cache
+.vscode
+.pytest_cache
+/install*
+/dist
+/_skbuild
+/_cmake_test_compile

BUILD.md

@@ -0,0 +1,131 @@
+<!--
+Copyright 2021-2022 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.
+
+-->
+
+# Overview
+
+The build system is designed to enable two different modes of use:
+1. Simple `pip install` for users
+2. Highly customizable incremental builds for developers
+
+We review each of these modes with examples.
+
+
+# Building for Users
+
+## Using install.py
+
+For releases <= 22.07, the main method for building cuNumeric was the `install.py` script.
+Although the underlying implementation has significantly changed, `install.py` still supports the
+same usage and same set of flags. For a full list of flags, users can run:
+
+```
+$ ./install.py --help
+```
+
+## Using Conda
+
+cuNumeric can be installed using Conda by pointing to the required channels (`-c`):
+
+```
+conda install -c nvidia -c conda-forge -c legate legate-core
+```
+
+## Using pip
+
+cuNumeric is not yet registered in a standard pip repository. However, users can still use the 
+pip installer to build and install cuNumeric. After downloading or cloning the cunumeric source,
+users can run the following in the cunumeric folder:
+
+```
+$ pip install .
+```
+or
+```
+$ python3 -m pip install .
+```
+
+This will install cuNumeric in the standard packages directory for the environment Python.
+Note: This is currently not sufficient for running cuNumeric programs. cuNumeric relies
+on the `legate` launcher from Legate core, which must be installed separately.
+For details on installing Legate, consult the [Legate repository](https://github.com/nv-legate/legate.core).
+
+### Advanced Customization
+
+If users need to customize details of the underlying CMake build, they can pass
+CMake flags through the `SKBUILD_CONFIGURE_OPTIONS` environment variable:
+
+```
+$ SKBUILD_CONFIGURE_OPTIONS="-D Legion_USE_CUDA:BOOL=ON" \
+  pip install .
+```
+An alternative syntax using `setup.py` with `scikit-build` is
+```
+$ python setup.py install -- -DLegion_USE_CUDA:BOOL=ON
+```
+
+# Building for Developers
+
+## Overview
+
+pip uses [scikit-build](https://scikit-build.readthedocs.io/en/latest/)
+in `setup.py` to drive the build and installation.  A `pip install` will trigger three general actions:
+
+1. CMake build and installation of C++ libraries
+2. CMake generation of configuration files and build-dependent Python files
+3. pip installation of Python files
+
+The CMake build can be configured independently of `pip`, allowing incremental C++ builds directly through CMake.
+This simplifies rebuilding `libcunumeric.so` either via command-line or via IDE.
+After building the C++ libraries, the `pip install` can be done in "editable" mode using the `-e` flag.
+This configures the Python site packages to import the Python source tree directly.
+The Python source can then be edited and used directly for testing without requiring a `pip install`.
+
+## Example
+
+There are several examples in the `scripts` folder. We walk through the steps in the `build-with-legate-separately-no-install.sh` here.
+We assume a pre-existing Legate CUDA build. For details on building Legate, consult the [Legate repository](https://github.com/nv-legate/legate.core).
+First, the CMake build needs to be configured:
+
+```
+$ cmake -S . -B build -GNinja -D legate_core_ROOT:STRING=path/to/legate/build
+```
+
+We point cuNumeric to the Legate *build* tree, not an installation.
+This generates all build-dependent headers and Python files.
+Once configured, we can build the C++ libraries:
+
+```
+$ cmake --build build
+```
+
+This will invoke Ninja (or make) to execute the build.
+Once the C++ libraries are available, we can do an editable (development) pip installation.
+
+```
+$ SKBUILD_BUILD_OPTIONS="-D FIND_CUNUMERIC_CPP=ON -D cunumeric_ROOT=$(pwd)/build" \
+  python3 -m pip install \
+  --root / --no-deps --no-build-isolation 
+  --editable .
+```
+
+The Python source tree and CMake build tree are now available with the environment Python 
+for running cuNumeric programs. The diagram below illustrates the 
+complete workflow for building both Legate core and cuNumeric.
+
+<img src="docs/figures/developer-build.png" alt="drawing" width="600"/>
+
+

CMakeLists.txt

@@ -0,0 +1,66 @@
+#=============================================================================
+# Copyright 2022 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.
+#=============================================================================
+
+cmake_minimum_required(VERSION 3.22.1 FATAL_ERROR)
+
+if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.13)
+  cmake_policy(SET CMP0077 NEW)
+  set(CMAKE_POLICY_DEFAULT_CMP0077 NEW)
+endif()
+
+if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.16)
+  cmake_policy(SET CMP0096 NEW)
+  set(CMAKE_POLICY_DEFAULT_CMP0096 NEW)
+endif()
+
+##############################################################################
+# - Download and initialize RAPIDS CMake helpers -----------------------------
+
+if(NOT EXISTS ${CMAKE_BINARY_DIR}/RAPIDS.cmake)
+  file(DOWNLOAD https://raw.githubusercontent.com/rapidsai/rapids-cmake/branch-22.08/RAPIDS.cmake
+       ${CMAKE_BINARY_DIR}/RAPIDS.cmake)
+endif()
+include(${CMAKE_BINARY_DIR}/RAPIDS.cmake)
+include(rapids-cmake)
+include(rapids-cpm)
+include(rapids-cuda)
+include(rapids-export)
+include(rapids-find)
+
+set(cunumeric_version 22.07.00)
+
+# For now we want the optimization flags to match on both normal make and cmake
+# builds so we override the cmake defaults here for release, this changes
+# -O3 to -O2 and removes -DNDEBUG
+set(CMAKE_CXX_FLAGS_RELEASE "-O2")
+set(CMAKE_CUDA_FLAGS_RELEASE "-O2")
+set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "-O2 -g")
+set(CMAKE_CUDA_FLAGS_RELWITHDEBINFO "-O2 -g")
+
+if(NOT SKBUILD)
+  project(cunumeric VERSION ${cunumeric_version} LANGUAGES C CXX)
+  include(cunumeric_cpp.cmake)
+else()
+  project(
+    cunumeric_python
+    VERSION ${cunumeric_version}
+    LANGUAGES # TODO: Building Python extension modules via the python_extension_module requires the C
+              # language to be enabled here. The test project that is built in scikit-build to verify
+              # various linking options for the python library is hardcoded to build with C, so until
+              # that is fixed we need to keep C.
+              C CXX)
+  include(cunumeric_python.cmake)
+endif()

MANIFEST.in

@@ -0,0 +1,2 @@
+include versioneer.py
+include cunumeric/_version.py

README.md

@@ -91,12 +91,12 @@ issues on GitHub.
 
 ## Building from Source
 
-Installation of cuNumeric is done with either `setup.py` for simple
-uses cases or `install.py` for more advanced use cases. The most common
-installation command is:
+Installation can be done the `install.py` script.
+For releases >= 22.10, `pip install` is now available.
+The most common installation command is:
 
 ```
-python setup.py --with-core <path-to-legate-core-installation>
+./install.py --with-core <path-to-legate-core-installation>
 ```
 
 This will build cuNumeric against the Legate Core installation and then
@@ -106,7 +106,7 @@ If Legate Core has been installed with CUDA support, a working cuTENSOR
 installation must also be provided to the installation command with the
 `--with-cutensor` option:
 ```
-python setup.py --with-core <path-to-legate-core-installation> --with-cutensor <path-to-cutensor-installation>
+./install.py --with-core <path-to-legate-core-installation> --with-cutensor <path-to-cutensor-installation>
 ```
 
 You can also specify an installation of [OpenBLAS](https://www.openblas.net/)
@@ -115,16 +115,14 @@ machine, you can inform the installation script using the `--with-openblas`
 option:
 
 ```
-python setup.py --with-openblas <path-to-OpenBLAS>
+./install.py --with-openblas <path-to-OpenBLAS>
 ```
 
 Advanced users can also invoke `install.py --help` to see options for
 configuring cuNumeric by invoking the `install.py` script directly.
+More information on building - including development workflows - can be found
+in the [build instructions](BUILD.md)
 
-Note that after the first invocation of `setup.py` or `install.py` this
-repository will remember the paths you provided with the installation options
-and they can be omitted in subsequent invocations unless you want to change
-them.
 
 ## Usage and Execution
 

cmake/Modules/cpm_helpers.cmake

@@ -0,0 +1,57 @@
+#=============================================================================
+# Copyright 2022 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.
+#=============================================================================
+
+function(get_cpm_git_args _out_var)
+
+  set(oneValueArgs TAG BRANCH REPOSITORY)
+  cmake_parse_arguments(GIT "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
+
+  set(repo_tag "")
+  set(gh_tag_prefix "")
+  # Default to specifying `GIT_REPOSITORY` and `GIT_TAG`
+  set(cpm_git_args GIT_REPOSITORY ${GIT_REPOSITORY})
+
+  if(GIT_BRANCH)
+    set(gh_tag_prefix "heads")
+    set(repo_tag "${GIT_BRANCH}")
+    list(APPEND cpm_git_args GIT_TAG ${GIT_BRANCH})
+  elseif(GIT_TAG)
+    set(gh_tag_prefix "tags")
+    set(repo_tag "${GIT_TAG}")
+    list(APPEND cpm_git_args GIT_TAG ${GIT_TAG})
+  endif()
+
+  # Remove `.git` suffix from repo URL
+  if(GIT_REPOSITORY MATCHES "^(.*)(\.git)$")
+    set(GIT_REPOSITORY "${CMAKE_MATCH_1}")
+  endif()
+  if(GIT_REPOSITORY MATCHES "github\.com")
+    # If retrieving from github use `.zip` URL to download faster
+    set(cpm_git_args URL "${GIT_REPOSITORY}/archive/refs/${gh_tag_prefix}/${repo_tag}.zip")
+  elseif(GIT_REPOSITORY MATCHES "gitlab\.com")
+    # GitLab archive URIs replace slashes with dashes
+    string(REPLACE "/" "-" archive_tag "${repo_tag}")
+    string(LENGTH "${GIT_REPOSITORY}" repo_name_len)
+    string(FIND "${GIT_REPOSITORY}" "/" repo_name_idx REVERSE)
+    math(EXPR repo_name_len "${repo_name_len} - ${repo_name_idx}")
+    string(SUBSTRING "${GIT_REPOSITORY}" ${repo_name_idx} ${repo_name_len} repo_name)
+    # If retrieving from gitlab use `.zip` URL to download faster
+    set(cpm_git_args URL "${GIT_REPOSITORY}/-/archive/${repo_tag}/${repo_name}-${archive_tag}.zip")
+  endif()
+
+  set(${_out_var} ${cpm_git_args} PARENT_SCOPE)
+
+endfunction()