Merge remote-tracking branch 'upstream/main' into debug-builds

Author: mdboom

cuda_bindings/build_hooks.py

@@ -33,13 +33,41 @@
 _extensions = None
 
 
+# Please keep in sync with the copy in cuda_core/build_hooks.py.
+def _import_get_cuda_path_or_home():
+    """Import get_cuda_path_or_home, working around PEP 517 namespace shadowing.
+
+    See https://github.com/NVIDIA/cuda-python/issues/1824 for why this helper is needed.
+    """
+    try:
+        import cuda.pathfinder
+    except ModuleNotFoundError as exc:
+        if exc.name not in ("cuda", "cuda.pathfinder"):
+            raise
+        try:
+            import cuda
+        except ModuleNotFoundError:
+            cuda = None
+
+        for p in sys.path:
+            sp_cuda = os.path.join(p, "cuda")
+            if os.path.isdir(os.path.join(sp_cuda, "pathfinder")):
+                cuda.__path__ = list(cuda.__path__) + [sp_cuda]
+                break
+        else:
+            raise ModuleNotFoundError(
+                "cuda-pathfinder is not installed in the build environment. "
+                "Ensure 'cuda-pathfinder>=1.5' is in build-system.requires."
+            )
+        import cuda.pathfinder
+
+    return cuda.pathfinder.get_cuda_path_or_home
+
+
 @functools.cache
 def _get_cuda_path() -> str:
-    # Not using cuda.pathfinder.get_cuda_path_or_home() here because this
-    # build backend runs in an isolated venv where the cuda namespace package
-    # from backend-path shadows the installed cuda-pathfinder. See #1803 for
-    # a workaround to apply after cuda-pathfinder >= 1.5 is released.
-    cuda_path = os.environ.get("CUDA_PATH", os.environ.get("CUDA_HOME"))
+    get_cuda_path_or_home = _import_get_cuda_path_or_home()
+    cuda_path = get_cuda_path_or_home()
     if not cuda_path:
         raise RuntimeError("Environment variable CUDA_PATH or CUDA_HOME is not set")
     print("CUDA path:", cuda_path)

cuda_bindings/pyproject.toml

@@ -6,6 +6,7 @@ requires = [
     "setuptools_scm[simple]>=8",
     "cython>=3.2,<3.3",
     "pyclibrary>=0.1.7",
+    "cuda-pathfinder>=1.5",
 ]
 build-backend = "build_hooks"
 backend-path = ["."]

cuda_core/build_hooks.py

@@ -28,13 +28,41 @@
 COMPILE_FOR_COVERAGE = bool(int(os.environ.get("CUDA_PYTHON_COVERAGE", "0")))
 
 
+# Please keep in sync with the copy in cuda_bindings/build_hooks.py.
+def _import_get_cuda_path_or_home():
+    """Import get_cuda_path_or_home, working around PEP 517 namespace shadowing.
+
+    See https://github.com/NVIDIA/cuda-python/issues/1824 for why this helper is needed.
+    """
+    try:
+        import cuda.pathfinder
+    except ModuleNotFoundError as exc:
+        if exc.name not in ("cuda", "cuda.pathfinder"):
+            raise
+        try:
+            import cuda
+        except ModuleNotFoundError:
+            cuda = None
+
+        for p in sys.path:
+            sp_cuda = os.path.join(p, "cuda")
+            if os.path.isdir(os.path.join(sp_cuda, "pathfinder")):
+                cuda.__path__ = list(cuda.__path__) + [sp_cuda]
+                break
+        else:
+            raise ModuleNotFoundError(
+                "cuda-pathfinder is not installed in the build environment. "
+                "Ensure 'cuda-pathfinder>=1.5' is in build-system.requires."
+            )
+        import cuda.pathfinder
+
+    return cuda.pathfinder.get_cuda_path_or_home
+
+
 @functools.cache
 def _get_cuda_path() -> str:
-    # Not using cuda.pathfinder.get_cuda_path_or_home() here because this
-    # build backend runs in an isolated venv where the cuda namespace package
-    # from backend-path shadows the installed cuda-pathfinder. See #1803 for
-    # a workaround to apply after cuda-pathfinder >= 1.5 is released.
-    cuda_path = os.environ.get("CUDA_PATH", os.environ.get("CUDA_HOME"))
+    get_cuda_path_or_home = _import_get_cuda_path_or_home()
+    cuda_path = get_cuda_path_or_home()
     if not cuda_path:
         raise RuntimeError("Environment variable CUDA_PATH or CUDA_HOME is not set")
     print("CUDA path:", cuda_path)

cuda_core/docs/source/install.rst

@@ -71,6 +71,56 @@ and likewise use ``cuda-version=13`` for CUDA 13.
 Note that to use ``cuda.core`` with nvJitLink installed from conda-forge requires ``cuda.bindings`` 12.8.0+.
 
 
+Development environment
+-----------------------
+
+The sections above cover end-user installation. The section below focuses on
+a repeatable *development* workflow (editable installs and running tests).
+
+Development with uv
+~~~~~~~~~~~~~~~~~~~
+
+`uv`_ is a fast Python package and project manager. For example, to work on
+``cuda-core`` against CUDA 13:
+
+.. code-block:: console
+
+   $ git clone https://github.com/NVIDIA/cuda-python
+   $ cd cuda-python/cuda_core
+   $ uv venv
+   $ source .venv/bin/activate   # On Windows: .venv\Scripts\activate
+   $ uv pip install -e .[cu13] --group test
+
+Run tests:
+
+.. code-block:: console
+
+   $ python -m pytest tests
+
+.. _uv: https://docs.astral.sh/uv/
+
+Development with pixi
+~~~~~~~~~~~~~~~~~~~~~
+
+`pixi`_ provides a reproducible development environment across the repository.
+From the repository root:
+
+.. code-block:: console
+
+   $ git clone https://github.com/NVIDIA/cuda-python
+   $ cd cuda-python
+   $ pixi run -e cu13 test-core
+
+To run all repository tests (pathfinder → bindings → core):
+
+.. code-block:: console
+
+   $ pixi run -e cu13 test
+
+Use ``-e cu12`` to test against CUDA 12 instead.
+
+.. _pixi: https://pixi.sh/
+
 Installing from Source
 ----------------------
 

cuda_core/pyproject.toml

@@ -7,6 +7,7 @@ requires = [
     "setuptools>=80",
     "setuptools-scm[simple]>=8",
     "Cython>=3.2,<3.3",
+    "cuda-pathfinder>=1.5"
 ]
 build-backend = "build_hooks"
 backend-path = ["."]

cuda_core/tests/test_build_hooks.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright (c) 2024-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2024-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
 """Tests for build_hooks.py build infrastructure.
@@ -24,6 +24,8 @@
 
 import pytest
 
+from cuda.pathfinder import get_cuda_path_or_home
+
 # build_hooks.py imports Cython and setuptools at the top level, so skip if not available
 pytest.importorskip("Cython")
 pytest.importorskip("setuptools")
@@ -68,6 +70,7 @@ def _check_version_detection(
 
         build_hooks._get_cuda_path.cache_clear()
         build_hooks._determine_cuda_major_version.cache_clear()
+        get_cuda_path_or_home.cache_clear()
 
         mock_env = {
             k: v
@@ -92,6 +95,7 @@ def test_env_var_override(self, version):
         """CUDA_CORE_BUILD_MAJOR env var override works with various versions."""
         build_hooks._get_cuda_path.cache_clear()
         build_hooks._determine_cuda_major_version.cache_clear()
+        get_cuda_path_or_home.cache_clear()
         with mock.patch.dict(os.environ, {"CUDA_CORE_BUILD_MAJOR": version}, clear=False):
             result = build_hooks._determine_cuda_major_version()
             assert result == version
@@ -125,6 +129,7 @@ def test_missing_cuda_path_raises_error(self):
         """RuntimeError is raised when CUDA_PATH/CUDA_HOME not set and no env var override."""
         build_hooks._get_cuda_path.cache_clear()
         build_hooks._determine_cuda_major_version.cache_clear()
+        get_cuda_path_or_home.cache_clear()
         with (
             mock.patch.dict(os.environ, {}, clear=True),
             pytest.raises(RuntimeError, match="CUDA_PATH or CUDA_HOME"),