From 0bd559b0d2b6d19cd04e9dd52e20a839ae2967b4 Mon Sep 17 00:00:00 2001 From: Vladislav Zhurba Date: Thu, 9 Jan 2025 16:20:55 -0800 Subject: [PATCH 1/3] Update source installation instuctions with Cython considerations --- cuda_bindings/README.md | 2 +- cuda_bindings/docs/source/install.md | 72 +++++++++------------------- 2 files changed, 24 insertions(+), 50 deletions(-) diff --git a/cuda_bindings/README.md b/cuda_bindings/README.md index 7a2d8fc85..c563f45c9 100644 --- a/cuda_bindings/README.md +++ b/cuda_bindings/README.md @@ -63,8 +63,8 @@ Latest dependencies can be found in [requirements.txt](https://github.com/NVIDIA Multiple testing options are available: -* Cython Unit Tests * Python Unit Tests +* Cython Unit Tests * Samples * Benchmark diff --git a/cuda_bindings/docs/source/install.md b/cuda_bindings/docs/source/install.md index 6bd307192..fe9237507 100644 --- a/cuda_bindings/docs/source/install.md +++ b/cuda_bindings/docs/source/install.md @@ -2,91 +2,65 @@ ## Runtime Requirements -CUDA Python is supported on all platforms that CUDA is supported. Specific -dependencies are as follows: +`cuda-python` supports the same platforms as CUDA. Runtime dependencies are: * Driver: Linux (450.80.02 or later) Windows (456.38 or later) * CUDA Toolkit 12.0 to 12.6 -```{note} Only the NVRTC redistributable component is required from the CUDA Toolkit. [CUDA Toolkit Documentation](https://docs.nvidia.com/cuda/index.html) Installation Guides can be used for guidance. Note that the NVRTC component in the Toolkit can be obtained via PYPI, Conda or Local Installer. +```{note} Only the NVRTC redistributable component is required from the CUDA Toolkit. [CUDA Toolkit Documentation](https://docs.nvidia.com/cuda/index.html) Installation Guides can be used for guidance. Note that the NVRTC component in the Toolkit can be obtained via PYPI, Conda or local installers. ``` ## Installing from PyPI -```{code-block} shell -pip install cuda-python +```console +$ pip install cuda-python ``` ## Installing from Conda -```{code-block} shell -conda install -c nvidia cuda-python +```console +$ conda install -c nvidia cuda-python ``` -Conda packages are assigned a dependency to CUDA Toolkit: +Conda packages have dependencies to CUDA Toolkit components: -* cuda-cudart (Provides CUDA headers to enable writting NVRTC kernels with CUDA types) +* cuda-cudart (Provides CUDA headers to enable writing NVRTC kernels with CUDA types) * cuda-nvrtc (Provides NVRTC shared library) ## Installing from Source -### Build Requirements +### Requirements -* CUDA Toolkit headers -* Cython -* pyclibrary +* CUDA Toolkit headers[^1] +* [requirements.txt](https://github.com/NVIDIA/cuda-python/blob/main/cuda_bindings/requirements.txt) -Remaining build and test dependencies are outlined in [requirements.txt](https://github.com/NVIDIA/cuda-python/blob/main/requirements.txt) +[^1]: User projects that `cimport` CUDA symbols in Cython must also use CUDA Toolkit (CTK) types as provided by the `cuda-python` major.minor version. This results in CTK headers becoming a transitive dependency of downstream projects through CUDA Python. -The version of CUDA Toolkit headers must match the major.minor of CUDA Python. Note that minor version compatibility will still be maintained. - -During the build process, environment variable `CUDA_HOME` or `CUDA_PATH` are used to find the location of CUDA headers. In particular, if your headers are located in path `/usr/local/cuda/include`, then you should set `CUDA_HOME` as follows: +Source builds require that the provided CUDA headers are of the same major.minor version as the `cuda-python` bindings you're trying to build. Despite of this requirement, note that the minor version compatibility is still maintained. Use the `CUDA_HOME` (or `CUDA_PATH`) environment variable to specify the location of your headers. For example, if your headers are located in `/usr/local/cuda/include`, then you should set `CUDA_HOME` with: +```console +$ export CUDA_HOME=/usr/local/cuda ``` -export CUDA_HOME=/usr/local/cuda + +```{note} Only `cydriver`, `cyruntime` and `cynvrtc` are impacted by the header requirement. ``` ### In-place To compile the extension in-place, run: -```{code-block} shell -python setup.py build_ext --inplace +```console +$ python setup.py build_ext --inplace ``` -To compile for debugging the extension modules with gdb, pass the `--debug` -argument to setup.py. +To compile for debugging the extension modules with gdb, pass the `--debug` argument to setup.py. ### Develop You can use -```{code-block} shell -pip install -e . -``` - -to install the module as editible in your current Python environment (e.g. for -testing of porting other libraries to use the binding). - -## Build the Docs - -```{code-block} shell -conda env create -f docs_src/environment-docs.yml -conda activate cuda-python-docs -``` -Then compile and install `cuda-python` following the steps above. - -```{code-block} shell -cd docs_src -make html -open build/html/index.html +```console +$ pip install -e . ``` -### Publish the Docs - -```{code-block} shell -git checkout gh-pages -cd docs_src -make html -cp -a build/html/. ../docs/ -``` +to install the module as editable in your current Python environment (e.g. for testing of porting other libraries to use the binding). From fd60a05b95742c386b75a3c430324849ddd09d23 Mon Sep 17 00:00:00 2001 From: Vladislav Zhurba Date: Thu, 9 Jan 2025 16:26:14 -0800 Subject: [PATCH 2/3] Direct README.md cython test header requirements to docs --- cuda_bindings/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cuda_bindings/README.md b/cuda_bindings/README.md index c563f45c9..9271ea9fc 100644 --- a/cuda_bindings/README.md +++ b/cuda_bindings/README.md @@ -78,7 +78,7 @@ To run these tests: ### Cython Unit Tests -Cython tests are located in `tests/cython` and need to be built. Furthermore they need CUDA Toolkit headers matching the major-minor of CUDA Python. To build them: +Cython tests are located in `tests/cython` and need to be built. These builds have the same CUDA Toolkit header requirements as [Installing from Source](https://nvidia.github.io/cuda-python/cuda-bindings/latest/install.html#requirements) where the major.minor version must match `cuda-python`. To build them: 1. Setup environment variable `CUDA_HOME` with the path to the CUDA Toolkit installation. 2. Run `build_tests` script located in `test/cython` appropriate to your platform. This will both cythonize the tests and build them. From 083347c6d771b74af94629eaa368bec16fae5022 Mon Sep 17 00:00:00 2001 From: Vladislav Zhurba Date: Tue, 14 Jan 2025 16:17:26 -0800 Subject: [PATCH 3/3] Apply feedback --- cuda_bindings/README.md | 14 +++++------ cuda_bindings/docs/source/install.md | 36 +++++++++------------------- cuda_core/README.md | 2 +- 3 files changed, 19 insertions(+), 33 deletions(-) diff --git a/cuda_bindings/README.md b/cuda_bindings/README.md index 9271ea9fc..3ece5667d 100644 --- a/cuda_bindings/README.md +++ b/cuda_bindings/README.md @@ -19,9 +19,9 @@ Differences between these options are described in [Installation](https://nvidia CUDA Python is supported on all platforms that CUDA is supported. Specific dependencies are as follows: * Driver: Linux (450.80.02 or later) Windows (456.38 or later) -* CUDA Toolkit 12.0 to 12.6 +* CUDA Toolkit 12.x -Only the NVRTC redistributable component is required from the CUDA Toolkit. [CUDA Toolkit Documentation](https://docs.nvidia.com/cuda/index.html) Installation Guides can be used for guidance. Note that the NVRTC component in the Toolkit can be obtained via PYPI, Conda or Local Installer. +Only the NVRTC and nvJitLink redistributable components are required from the CUDA Toolkit, which can be obtained via PyPI, Conda, or local installers (as described in the CUDA Toolkit [Windows](https://docs.nvidia.com/cuda/cuda-installation-guide-microsoft-windows/index.html) and [Linux](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html) Installation Guides). ### Supported Python Versions @@ -73,18 +73,18 @@ Multiple testing options are available: Responsible for validating different binding usage patterns. Unit test `test_kernelParams.py` is particularly special since it demonstrates various approaches in setting up kernel launch parameters. To run these tests: -* `python -m pytest tests/` against local builds +* `python -m pytest tests/` against editable installations * `pytest tests/` against installed packages ### Cython Unit Tests -Cython tests are located in `tests/cython` and need to be built. These builds have the same CUDA Toolkit header requirements as [Installing from Source](https://nvidia.github.io/cuda-python/cuda-bindings/latest/install.html#requirements) where the major.minor version must match `cuda-python`. To build them: +Cython tests are located in `tests/cython` and need to be built. These builds have the same CUDA Toolkit header requirements as [Installing from Source](https://nvidia.github.io/cuda-python/cuda-bindings/latest/install.html#requirements) where the major.minor version must match `cuda.bindings`. To build them: 1. Setup environment variable `CUDA_HOME` with the path to the CUDA Toolkit installation. 2. Run `build_tests` script located in `test/cython` appropriate to your platform. This will both cythonize the tests and build them. To run these tests: -* `python -m pytest tests/cython/` against local builds +* `python -m pytest tests/cython/` against editable installations * `pytest tests/cython/` against installed packages ### Samples @@ -102,7 +102,7 @@ In addition, extra examples are included: wrappers of the driver API. To run these samples: -* `python -m pytest tests/cython/` against local builds +* `python -m pytest tests/cython/` against editable installations * `pytest tests/cython/` against installed packages ### Benchmark (WIP) @@ -110,5 +110,5 @@ To run these samples: Benchmarks were used for performance analysis during initial release of CUDA Python. Today they need to be updated the 12.x toolkit and are work in progress. The intended way to run these benchmarks was: -* `python -m pytest --benchmark-only benchmark/` against local builds +* `python -m pytest --benchmark-only benchmark/` against editable installations * `pytest --benchmark-only benchmark/` against installed packages diff --git a/cuda_bindings/docs/source/install.md b/cuda_bindings/docs/source/install.md index fe9237507..b5c3e6254 100644 --- a/cuda_bindings/docs/source/install.md +++ b/cuda_bindings/docs/source/install.md @@ -2,12 +2,13 @@ ## Runtime Requirements -`cuda-python` supports the same platforms as CUDA. Runtime dependencies are: +`cuda.bindings` supports the same platforms as CUDA. Runtime dependencies are: * Driver: Linux (450.80.02 or later) Windows (456.38 or later) -* CUDA Toolkit 12.0 to 12.6 +* CUDA Toolkit 12.x -```{note} Only the NVRTC redistributable component is required from the CUDA Toolkit. [CUDA Toolkit Documentation](https://docs.nvidia.com/cuda/index.html) Installation Guides can be used for guidance. Note that the NVRTC component in the Toolkit can be obtained via PYPI, Conda or local installers. +```{note} +Only the NVRTC and nvJitLink redistributable components are required from the CUDA Toolkit, which can be obtained via PyPI, Conda, or local installers (as described in the CUDA Toolkit [Windows](https://docs.nvidia.com/cuda/cuda-installation-guide-microsoft-windows/index.html) and [Linux](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html) Installation Guides). ``` ## Installing from PyPI @@ -19,48 +20,33 @@ $ pip install cuda-python ## Installing from Conda ```console -$ conda install -c nvidia cuda-python +$ conda install -c conda-forge cuda-python ``` -Conda packages have dependencies to CUDA Toolkit components: - -* cuda-cudart (Provides CUDA headers to enable writing NVRTC kernels with CUDA types) -* cuda-nvrtc (Provides NVRTC shared library) - ## Installing from Source ### Requirements * CUDA Toolkit headers[^1] -* [requirements.txt](https://github.com/NVIDIA/cuda-python/blob/main/cuda_bindings/requirements.txt) -[^1]: User projects that `cimport` CUDA symbols in Cython must also use CUDA Toolkit (CTK) types as provided by the `cuda-python` major.minor version. This results in CTK headers becoming a transitive dependency of downstream projects through CUDA Python. +[^1]: User projects that `cimport` CUDA symbols in Cython must also use CUDA Toolkit (CTK) types as provided by the `cuda.bindings` major.minor version. This results in CTK headers becoming a transitive dependency of downstream projects through CUDA Python. -Source builds require that the provided CUDA headers are of the same major.minor version as the `cuda-python` bindings you're trying to build. Despite of this requirement, note that the minor version compatibility is still maintained. Use the `CUDA_HOME` (or `CUDA_PATH`) environment variable to specify the location of your headers. For example, if your headers are located in `/usr/local/cuda/include`, then you should set `CUDA_HOME` with: +Source builds require that the provided CUDA headers are of the same major.minor version as the `cuda.bindings` you're trying to build. Despite this requirement, note that the minor version compatibility is still maintained. Use the `CUDA_HOME` (or `CUDA_PATH`) environment variable to specify the location of your headers. For example, if your headers are located in `/usr/local/cuda/include`, then you should set `CUDA_HOME` with: ```console $ export CUDA_HOME=/usr/local/cuda ``` -```{note} Only `cydriver`, `cyruntime` and `cynvrtc` are impacted by the header requirement. -``` - -### In-place - -To compile the extension in-place, run: - -```console -$ python setup.py build_ext --inplace +```{note} +Only `cydriver`, `cyruntime` and `cynvrtc` are impacted by the header requirement. ``` -To compile for debugging the extension modules with gdb, pass the `--debug` argument to setup.py. - -### Develop +### Editable Install You can use ```console -$ pip install -e . +$ pip install -v -e . ``` to install the module as editable in your current Python environment (e.g. for testing of porting other libraries to use the binding). diff --git a/cuda_core/README.md b/cuda_core/README.md index f66d05e1b..de68bc9e4 100644 --- a/cuda_core/README.md +++ b/cuda_core/README.md @@ -39,5 +39,5 @@ for more details, including how to sign your commits. ## Testing To run these tests: -* `python -m pytest tests/` against local builds +* `python -m pytest tests/` against editable installations * `pytest tests/` against installed packages