cuda.bindings: integrate CUDA 12 source with shared build tooling (#3173)

* Integrate the CUDA 12 source with shared build and test helpers

Signed-off-by: Ralf W. Grosse-Kunstleve <rgrossekunst@nvidia.com>

* test(bindings): isolate CUDA 12 graph capture by thread

Signed-off-by: Ralf W. Grosse-Kunstleve <rgrossekunst@nvidia.com>

* test: classify CUDA 12 bindings alongside CUDA 13

Signed-off-by: Ralf W. Grosse-Kunstleve <rgrossekunst@nvidia.com>

* Restore the security scan for the integrated CUDA 12 sources

Signed-off-by: Ralf W. Grosse-Kunstleve <rgrossekunst@nvidia.com>

* Remove superseded CUDA 12 package benchmarks

Signed-off-by: Ralf W. Grosse-Kunstleve <rgrossekunst@nvidia.com>

* Document CUDA 12 support for Python 3.15

Signed-off-by: Ralf W. Grosse-Kunstleve <rgrossekunst@nvidia.com>

* Enable pre-commit checks for the integrated CUDA 12 source

Signed-off-by: Ralf W. Grosse-Kunstleve <rgrossekunst@nvidia.com>

* Defer CUDA 12 runtime backports to a focused maintenance layer

Signed-off-by: Ralf W. Grosse-Kunstleve <rgrossekunst@nvidia.com>

* Defer CUDA 12 NVML test maintenance to CI integration

Signed-off-by: Ralf W. Grosse-Kunstleve <rgrossekunst@nvidia.com>

* Pin CUDA 12 documentation links to a published snapshot

Signed-off-by: Ralf W. Grosse-Kunstleve <rgrossekunst@nvidia.com>

---------

Signed-off-by: Ralf W. Grosse-Kunstleve <rgrossekunst@nvidia.com>

Author: rwgk

.github/labeler.yml

@@ -8,6 +8,7 @@
 cuda.bindings:
   - changed-files:
     - any-glob-to-any-file:
+      - 'cuda_bindings_12/**'
       - 'cuda_bindings_13/**'
       - 'samples/cuda_bindings/**'
 

.github/workflows/bandit.yml

@@ -42,10 +42,8 @@ jobs:
           echo "codes=$(uvx toml2json ./ruff.toml | jq -r '.lint.ignore | map(select(test("^S\\d+"))) | join(",")')" >> "$GITHUB_OUTPUT"
       - name: Perform Bandit Analysis using Ruff
         uses: astral-sh/ruff-action@278981a28ce3188b1e39527901f38254bf3aac89  # v4.1.0
-        # Preserve the inactive CUDA 12 snapshot; the source-integration layer
-        # adapts its security annotations and removes this temporary exclusion.
         with:
-          args: "check --select S --ignore ${{ steps.ignore-codes.outputs.codes }} --extend-exclude cuda_bindings_12 --output-format sarif --output-file results.sarif"
+          args: "check --select S --ignore ${{ steps.ignore-codes.outputs.codes }} --output-format sarif --output-file results.sarif"
       - name: Upload SARIF file
         uses: github/codeql-action/upload-sarif@24c54180a607b1449ed407dd24f251e4e9147c8d  # v4.38.3
         with:

.gitignore

@@ -40,6 +40,25 @@ cuda_bindings_13/cuda/bindings/_internal/runtime.pyx
 cuda_bindings_13/cuda/bindings/_internal/runtime_ptds.pyx
 cuda_bindings_13/cuda/bindings/utils/_get_handle.pyx
 
+# CUDA 12 bindings source generation
+cuda_bindings_12/cuda/bindings/_bindings/cyruntime.pxd
+cuda_bindings_12/cuda/bindings/_bindings/cyruntime.pyx
+cuda_bindings_12/cuda/bindings/_bindings/cyruntime_ptds.pxd
+cuda_bindings_12/cuda/bindings/_bindings/cyruntime_ptds.pyx
+cuda_bindings_12/cuda/bindings/_internal/cufile.pyx
+cuda_bindings_12/cuda/bindings/_internal/driver.pyx
+cuda_bindings_12/cuda/bindings/_internal/nvfatbin.pyx
+cuda_bindings_12/cuda/bindings/_internal/nvjitlink.pyx
+cuda_bindings_12/cuda/bindings/_internal/nvml.pyx
+cuda_bindings_12/cuda/bindings/_internal/nvrtc.pyx
+cuda_bindings_12/cuda/bindings/_internal/nvvm.pyx
+cuda_bindings_12/cuda/bindings/cyruntime.pxd
+cuda_bindings_12/cuda/bindings/cyruntime.pyx
+cuda_bindings_12/cuda/bindings/cyruntime_functions.pxi
+cuda_bindings_12/cuda/bindings/cyruntime_types.pxi
+cuda_bindings_12/cuda/bindings/runtime.pxd
+cuda_bindings_12/cuda/bindings/runtime.pyx
+
 # Version files from setuptools_scm
 _version.py
 

.pre-commit-config.yaml

@@ -14,9 +14,6 @@ ci:
 
 # Please update the rev: SHAs below with this command:
 # pre-commit autoupdate --freeze
-# This unchanged maintenance-source import is inactive until its integration layer.
-exclude: ^cuda_bindings_12/
-
 repos:
   # Runs first so a leaked credential blocks the commit before any formatter runs.
   # Self-installing: the hook downloads a pinned, checksum-verified trufflehog on
@@ -31,7 +28,7 @@ repos:
     hooks:
       - id: ruff-check
         args: [--fix, --show-fixes]
-        exclude: (^cuda_bindings_13/cuda/bindings/_internal/_fast_enum\.py$)|(.*\.pyi$)
+        exclude: (^cuda_bindings_(?:12|13)/cuda/bindings/_internal/_fast_enum\.py$)|(.*\.pyi$)
       - id: ruff-format
         exclude: .*\.pyi$
 
@@ -71,7 +68,7 @@ repos:
         name: Check generated-file seals
         entry: python ./toolshed/check_generated_file_seals.py
         language: python
-        files: ^cuda_bindings_13/
+        files: ^cuda_bindings_(?:12|13)/
         types: [text]
 
       - id: check-pixi-cuda-version
@@ -96,6 +93,9 @@ repos:
           - "_" # fake script name, because bash considers $0 (the first argument) to be the script name
         language: system
         files: '^.*/docs/source/.*\.md$'
+        # The imported CUDA 12.9 documentation retains its historical MyST
+        # sources; new documentation elsewhere must continue to use reST.
+        exclude: '^cuda_bindings_12/docs/source/'
 
       - id: stubgen-pyx-cuda-core
         name: Generate .pyi stubs for cuda_core
@@ -155,7 +155,7 @@ repos:
     rev: "3e8a8703264a2f4a69428a0aa4dcb512790b2c8c"  # frozen: v6.0.0
     hooks:
     - id: check-added-large-files
-      exclude: cuda_bindings_13/cuda/bindings/nvml.pyx
+      exclude: '^(?:cuda_bindings_13/cuda/bindings/nvml\.pyx|cuda_bindings_12/cuda/bindings/(?:driver\.pyx|runtime\.pyx\.in|nvml\.pyx))$'
     - id: check-case-conflict
     - id: check-docstring-first
     - id: check-merge-conflict
@@ -164,14 +164,14 @@ repos:
     - id: check-yaml
     - id: debug-statements
     - id: end-of-file-fixer
-      exclude: &gen_exclude '^(?:cuda_python/README\.md|(?:.*/)?CLAUDE\.md|(?:.*/)?\.git_archival\.txt|cuda_bindings_13/cuda/bindings/.*\.in?|cuda_bindings_13/docs/source/module/.*\.rst?|.*\.pyi)$'
+      exclude: &gen_exclude '^(?:cuda_python/README\.md|(?:.*/)?CLAUDE\.md|(?:.*/)?\.git_archival\.txt|cuda_bindings_(?:12|13)/cuda/bindings/.*\.in?|cuda_bindings_(?:12|13)/docs/source/module/.*\.rst?|.*\.pyi)$'
     - id: mixed-line-ending
     - id: trailing-whitespace
       exclude: |
         (?x)^(?:
           cuda_python/README\.md|
-          cuda_bindings_13/cuda/bindings/.*\.in?|
-          cuda_bindings_13/docs/source/module/.*\.rst?|
+          cuda_bindings_(?:12|13)/cuda/bindings/.*\.in?|
+          cuda_bindings_(?:12|13)/docs/source/module/.*\.rst?|
           .*\.patch$
         )$
 
@@ -213,7 +213,7 @@ repos:
     hooks:
       - id: cython-lint
         args: [--no-pycodestyle]
-        exclude: ^cuda_bindings_13/
+        exclude: ^cuda_bindings_(?:12|13)/
         additional_dependencies:
           - Cython==3.2.9
 

benchmarks/cuda_bindings/runner/runtime.py

@@ -30,7 +30,10 @@ def ensure_context() -> int:
     assert_drv(err)
     _device = device
 
-    err, ctx = cuda.cuCtxCreate(None, 0, device)
+    if cuda.CUDA_VERSION < 13000:
+        err, ctx = cuda.cuCtxCreate(0, device)
+    else:
+        err, ctx = cuda.cuCtxCreate(None, 0, device)
     assert_drv(err)
     _ctx = ctx
     return ctx

cuda_bindings_12/DESCRIPTION.rst

@@ -5,11 +5,14 @@
 cuda-bindings: Low-level CUDA interfaces
 ****************************************
 
-`cuda.bindings <https://nvidia.github.io/cuda-python/cuda-bindings/>`_ is a standard set of low-level interfaces, providing full coverage of and 1:1 access to the CUDA host APIs from Python. Checkout the `Overview <https://nvidia.github.io/cuda-python/cuda-bindings/latest/overview.html>`_ for the workflow and performance results.
+.. Keep documentation URLs aligned with README.md and build_hooks.py.
+   Use a published CUDA 12 snapshot; latest follows the current CUDA major.
 
-* `Repository <https://github.com/NVIDIA/cuda-python/tree/main/cuda_bindings>`_
-* `Documentation <https://nvidia.github.io/cuda-python/cuda-bindings/>`_
-* `Examples <https://github.com/NVIDIA/cuda-python/tree/main/cuda_bindings/examples>`_
+`cuda.bindings <https://nvidia.github.io/cuda-python/cuda-bindings/12.9.7/>`_ is a standard set of low-level interfaces, providing full coverage of and 1:1 access to the CUDA host APIs from Python. Checkout the `Overview <https://nvidia.github.io/cuda-python/cuda-bindings/12.9.7/overview.html>`_ for the workflow and performance results.
+
+* `Repository <https://github.com/NVIDIA/cuda-python/tree/main/cuda_bindings_12>`_
+* `Documentation <https://nvidia.github.io/cuda-python/cuda-bindings/12.9.7/>`_
+* `Examples <https://github.com/NVIDIA/cuda-python/tree/main/cuda_bindings_12/examples>`_
 * `Issue tracker <https://github.com/NVIDIA/cuda-python/issues/>`_
 
-For the installation instruction, please refer to the `Installation <https://nvidia.github.io/cuda-python/cuda-bindings/latest/install.html>`_ page.
+For the installation instruction, please refer to the `Installation <https://nvidia.github.io/cuda-python/cuda-bindings/12.9.7/install.html>`_ page.

cuda_bindings_12/LICENSE

@@ -176,3 +176,28 @@ Copyright (c) 2024-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
       of your accepting any such warranty or additional liability.
 
    END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.

cuda_bindings_12/MANIFEST.in

@@ -1,8 +1,11 @@
 # SPDX-FileCopyrightText: Copyright (c) 2024-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-recursive-include cuda/ *.pyx *.pxd *.pxi
+recursive-include cuda/ *.pyx *.pxd *.pxi *.pyx.in *.pxd.in *.pxi.in *.h
+include build_hooks.py
 # at least with setuptools 75.0.0 this folder was added erroneously
 # to the payload, causing file copying to the build environment failed
 exclude cuda/bindings cuda?bindings
 exclude cuda/bindings/_bindings cuda?bindings?_bindings
+# package-local shared PEP 517 helper
+include _build_shared.py

cuda_bindings_12/README.md

@@ -1,10 +1,13 @@
 # `cuda.bindings`: Low-level CUDA interfaces
 
-`cuda.bindings` is a standard set of low-level interfaces, providing full coverage of and access to the CUDA host APIs from Python. Checkout the [Overview page](https://nvidia.github.io/cuda-python/cuda-bindings/latest/overview.html) for the workflow and performance results.
+`cuda.bindings` is a standard set of low-level interfaces, providing full coverage of and access to the CUDA host APIs from Python. Checkout the [Overview page](https://nvidia.github.io/cuda-python/cuda-bindings/12.9.7/overview.html) for the workflow and performance results.
+
+<!-- Keep documentation URLs aligned with DESCRIPTION.rst and build_hooks.py.
+Use a published CUDA 12 snapshot; latest follows the current CUDA major. -->
 
 ## Installing
 
-Please refer to the [Installation page](https://nvidia.github.io/cuda-python/cuda-bindings/latest/install.html) for instructions and required/optional dependencies.
+Please refer to the [Installation page](https://nvidia.github.io/cuda-python/cuda-bindings/12.9.7/install.html) for instructions and required/optional dependencies.
 
 ## Developing
 
@@ -31,7 +34,7 @@ To run these tests:
 
 ### 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.bindings`. 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/12.9.7/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.
@@ -60,8 +63,5 @@ To run these samples:
 
 ### Benchmark
 
-Allows for analyzing binding performance using plugin [pytest-benchmark](https://github.com/ionelmc/pytest-benchmark).
-
-To run these benchmarks:
-* `python -m pytest --benchmark-only benchmarks/` against editable installations
-* `pytest --benchmark-only benchmarks/` against installed packages
+See the shared [cuda.bindings benchmark harness](../benchmarks/cuda_bindings/README.md)
+for performance benchmarks and usage instructions.

cuda_bindings_12/_build_shared.py

@@ -0,0 +1 @@
+../cuda_bindings_13/_build_shared.py