Release 22.10.00

Release v22.10.00

.gitattributes

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

.github/release.yml

@@ -0,0 +1,17 @@
+changelog:
+  exclude:
+    labels:
+      - category:task
+  categories:
+    - title: 🐛 Bug Fixes
+      labels:
+        - category:bug-fix
+    - title: 🚀 New Features
+      labels:
+        - category:new-feature
+    - title: 🛠️ Improvements
+      labels:
+        - category:improvement
+    - title: 📖 Documentation
+      labels:
+        - category:documentation

.github/workflows/ci.yml

@@ -49,7 +49,7 @@ jobs:
           /data/github-runner/legate-bin/setup.sh
           cd legate-ci/github-ci/legate.core
           rm -rf ngc-artifacts || true
-          ./build.sh > ${COMMIT}-build.log 2>&1
+          ./build-conda.sh > ${COMMIT}-build.log 2>&1
       - name: Process Output
         run: |
           cd legate-ci/github-ci/legate.core

.github/workflows/require-labels.yml

@@ -0,0 +1,18 @@
+name: Pull Request Labels
+on:
+  pull_request:
+    types: [opened, labeled, unlabeled, synchronize]
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Delay checking labels if PR is just created
+        if: ${{ github.event.action == 'opened' }}
+        run: sleep 300s
+        shell: bash
+      - name: Check Labels
+        uses: mheap/github-action-required-labels@v2
+        with:
+          mode: exactly
+          count: 1
+          labels: "category:new-feature, category:improvement, category:bug-fix, category:task"

.gitignore

@@ -20,10 +20,18 @@
 *.aux
 *.json
 *.dylib
-legate/core/install_info.py
+legate/install_info.py
+/dist
 /build
 /legion
 /install*
+/_skbuild
 config.mk
 /docs/legate/core/build
+/docs/legate/core/source/api/generated
 *.egg-info
+.cache
+.coverage
+.vscode
+_cmake_test_compile
+!cmake/versions.json

.pre-commit-config.yaml

@@ -4,11 +4,11 @@ repos:
       hooks:
             - id: isort
     - repo: https://github.com/psf/black
-      rev: 22.6.0
+      rev: 22.8.0
       hooks:
             - id: black
     - repo: https://github.com/PyCQA/flake8
-      rev: 4.0.1
+      rev: 5.0.4
       hooks:
             - id: flake8
     - repo: https://github.com/pre-commit/mirrors-clang-format

BUILD.md

@@ -0,0 +1,123 @@
+<!--
+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 `install.py` helper script or `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 Legate 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
+
+Legate 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
+
+Legate is not yet registered in a standard pip repository. However, users can still use the
+pip installer to build and install Legate. After downloading or cloning the legate.core source,
+users can run the following in the legate.core folder:
+
+```
+$ pip install .
+```
+or
+```
+$ python3 -m pip install .
+```
+
+This will install Legate in the standard packages directory for the environment Python.
+
+### 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 another `pip install`.
+
+## Example
+
+There are several examples in the `scripts` folder. We walk through the steps in the `build-separately-no-install.sh` here.
+First, the CMake build needs to be configured, e.g.:
+
+```
+$ cmake -S . -B build -GNinja -D Legion_USE_CUDA=ON
+```
+
+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_LEGATE_CORE_CPP=ON -D legate_core_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 Legate programs. The diagram below illustrates the
+complete workflow for building both Legate core and a downstream package [cuNumeric]()
+
+<img src="docs/figures/developer-build.png" alt="drawing" width="600"/>

CMakeLists.txt

@@ -0,0 +1,119 @@
+#=============================================================================
+# 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(POLICY CMP0060)
+  # Link libraries by full path even in implicit directories
+  # https://cmake.org/cmake/help/latest/policy/CMP0060.html#policy:CMP0060
+  cmake_policy(SET CMP0060 NEW)
+  set(CMAKE_POLICY_DEFAULT_CMP0060 NEW)
+endif()
+
+if(POLICY CMP0077)
+  # option() honors normal variables
+  # https://cmake.org/cmake/help/latest/policy/CMP0077.html
+  cmake_policy(SET CMP0077 NEW)
+  set(CMAKE_POLICY_DEFAULT_CMP0077 NEW)
+endif()
+
+if(POLICY CMP0096)
+  # The project() command preserves leading zeros in version components
+  # https://cmake.org/cmake/help/latest/policy/CMP0096.html
+  cmake_policy(SET CMP0096 NEW)
+  set(CMAKE_POLICY_DEFAULT_CMP0096 NEW)
+endif()
+
+if(POLICY CMP0126)
+  # make set(CACHE) command not remove normal variable of the same name from the current scope
+  # https://cmake.org/cmake/help/latest/policy/CMP0126.html
+  cmake_policy(SET CMP0126 NEW)
+  set(CMAKE_POLICY_DEFAULT_CMP0126 NEW)
+endif()
+
+if(POLICY CMP0135)
+  # make the timestamps of ExternalProject_ADD match the download time
+  # https://cmake.org/cmake/help/latest/policy/CMP0135.html
+  cmake_policy(SET CMP0135 NEW)
+  set(CMAKE_POLICY_DEFAULT_CMP0135 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(legate_core_version 22.10.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_DEBUG "-O0 -g")
+set(CMAKE_CUDA_FLAGS_DEBUG "-O0 -g")
+set(CMAKE_CXX_FLAGS_RELEASE "-O2")
+set(CMAKE_CUDA_FLAGS_RELEASE "-O2")
+set(CMAKE_CXX_FLAGS_MINSIZEREL "-Os")
+set(CMAKE_CUDA_FLAGS_MINSIZEREL "-Os")
+set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "-O2 -g")
+set(CMAKE_CUDA_FLAGS_RELWITHDEBINFO "-O2 -g")
+
+if(NOT SKBUILD)
+  project(legate_core VERSION ${legate_core_version} LANGUAGES C CXX)
+  include(${CMAKE_CURRENT_SOURCE_DIR}/legate_core_cpp.cmake)
+else()
+  project(
+    legate_core_python
+    VERSION ${legate_core_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(${CMAKE_CURRENT_SOURCE_DIR}/legate_core_python.cmake)
+endif()
+
+if(CMAKE_GENERATOR STREQUAL "Ninja")
+  function(add_touch_legate_core_ninja_build_target)
+    set(_suf )
+    set(_depends )
+    if(SKBUILD)
+      set(_suf "_python")
+    endif()
+    foreach(_dep IN ITEMS legion_core legion_core_python
+                          Legion LegionRuntime
+                          Realm RealmRuntime
+                          Regent)
+      if(TARGET ${_dep})
+        list(APPEND _depends ${_dep})
+      endif()
+    endforeach()
+    add_custom_target("touch_legion_core${_suf}_ninja_build" ALL
+      COMMAND ${CMAKE_COMMAND} -E touch_nocreate "${CMAKE_CURRENT_BINARY_DIR}/build.ninja"
+      COMMENT "touch build.ninja so ninja doesn't re-run CMake on rebuild"
+      VERBATIM DEPENDS ${_depends}
+    )
+  endfunction()
+  add_touch_legate_core_ninja_build_target()
+endif()

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to Legate Core
 
-Legate Core is an open-source project released under the [Apache license](LICENSE).  We welcome any and all contributions, and we hope that you can help us develop a strong community.
+Legate Core is an open-source project released under the [Apache license, version 2.0](https://www.apache.org/licenses/LICENSE-2.0).  We welcome any and all contributions, and we hope that you can help us develop a strong community.
 
 ## How to begin
 
@@ -10,7 +10,7 @@ Once you are ready to start development, we ask you to work on a [fork](https://
 
 ## The Legalese: Developer Certificate of Origin
 
-Legate Core is released under the open-source Apache license (see our [LICENSE](LICENSE) file) free to use, modify, and redistribute.  To ensure that the license can be exercised without encumbrance, we ask you that you only contribute your own work or work to which you have the intellectual rights.  To that end, we employ the Developer's Certificate of Origin (DCO), which is the lightweight mechanism for you to certify that you are legally able to make your contribution. Here is the full text of the certificate (also available at [DeveloperCertificate.org](DeveloperCertificate.org)):
+Legate Core is released under the [Apache license, version 2.0](https://www.apache.org/licenses/LICENSE-2.0) and is free to use, modify, and redistribute.  To ensure that the license can be exercised without encumbrance, we ask you that you only contribute your own work or work to which you have the intellectual rights.  To that end, we employ the Developer's Certificate of Origin (DCO), which is the lightweight mechanism for you to certify that you are legally able to make your contribution. Here is the full text of the certificate (also available at [DeveloperCertificate.org](https://DeveloperCertificate.org)):
 
 ````
 Developer Certificate of Origin
@@ -61,12 +61,14 @@ Please use your real name and a valid email address at which you can be reached.
 
 ## Review Process
 
-We are really grateful that you are thinking of contributing to Legate Core.  We will make every effort to review your contributions as soon as possible.  
+We are really grateful that you are thinking of contributing to Legate Core.  We will make every effort to review your contributions as soon as possible.
 
 As we suggested at the beginning of this document, it will be really helpful to start with an issue unless your proposed change is really trivial.  An issue will help to save work in the review process (e.g., maybe somebody is already working on exactly the same thing you want to work on).  After you open your pull request (PR), there usually will be a community feedback that often will require further changes to your contribution (the usual open-source process).  Usually, this will conclude in the PR being merged by a maintainer, but on rare occasions a PR may be rejected.  This may happen, for example, if the PR appears abandoned (no response to the community feedback) or if the PR does not seem to be approaching community acceptance in a reasonable time frame.  In any case, an explanation will always be given why a PR is closed.  Even if a PR is closed for some reason, it may always be reopened if the situation evolves (feel free to comment on closed PRs to discuss reopening them).
 
 ## Code Formatting Requirements
 
-Legate Core has a set of coding standards that are expected from all the code merged into the project.  The coding standards are defined by the set of tools we use to format our code.  We use the [pre-commit](https://pre-commit.com/) framework to run our formatting tools.  Our specific setup of pre-commit is defined in [.pre-commit-config.yaml](.pre-commit-config.yaml).  The easiest way to meet the coding standards is to simply use the pre-commit framework to run all the checks for you.  Please visit the [pre-commit project page](https://pre-commit.com/) for pre-commit installation and usage instructions.  Once pre-commit is installed in the Legate Core repo, all the checks and formatting will be run on every commit, but one can also run the checks explicitly as detailed in pre-commit documentation.
+Legate Core has a set of coding standards that are expected from all the code merged into the project.  The coding standards are defined by the set of tools we use to format our code.  We use the [pre-commit](https://pre-commit.com/) framework to run our formatting tools.  The easiest way to meet the coding standards is to simply use the pre-commit framework to run all the checks for you.  Please visit the [pre-commit project page](https://pre-commit.com/) for pre-commit installation and usage instructions.  Once pre-commit is installed in the cuNumeric repo, all the checks and formatting will be run on every commit, but one can also run the checks explicitly as detailed in pre-commit documentation.
+
+
 
 We hope that the automation of our formatting checks will make it easy to comply with our coding standards.  If you encounter problems with code formatting, however, please let us know in a comment on your PR, and we will do our best to help.

MANIFEST.in

@@ -0,0 +1,3 @@
+include versioneer.py
+include legate/_version.py
+include legate/py.typed