Merge branch 'main' into codex/pathfinder-windows-arch-search-ctk-next

Author: isVoid

.github/actions/griffe-api-check/action.yml

@@ -0,0 +1,44 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+name: griffe API check
+
+description: >-
+  Check a package's public API (as defined by `__all__`) for changes using
+  griffe.
+
+inputs:
+  package-name:
+    description: "Importable package name to check, e.g. cuda.core"
+    required: true
+  package-dir:
+    description: "Directory to search for the package sources, e.g. cuda_core"
+    required: true
+  merge-base:
+    description: >-
+      Git ref/sha to compare the current code against, typically the PR's
+      merge-base with its target branch.
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Install uv
+      uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39  # v8.2.0
+      with:
+        enable-cache: false
+
+    - name: Check API
+      shell: bash --noprofile --norc -euo pipefail {0}
+      env:
+        PACKAGE_NAME: ${{ inputs.package-name }}
+        PACKAGE_DIR: ${{ inputs.package-dir }}
+        MERGE_BASE: ${{ inputs.merge-base }}
+      run: |
+        uvx griffe check "$PACKAGE_NAME" \
+          --search "$PACKAGE_DIR" \
+          --find-stubs-packages \
+          --against "$MERGE_BASE" \
+          --format github \
+          2>&1

.github/workflows/ci.yml

@@ -103,6 +103,7 @@ jobs:
       test_bindings: ${{ steps.compose.outputs.test_bindings }}
       test_core: ${{ steps.compose.outputs.test_core }}
       test_pathfinder: ${{ steps.compose.outputs.test_pathfinder }}
+      pr_merge_base: ${{ steps.filter.outputs.merge_base }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
@@ -156,6 +157,7 @@ jobs:
             echo "python_meta=$(has_match '^cuda_python/')"
             echo "test_helpers=$(has_match '^cuda_python_test_helpers/')"
             echo "shared=$(has_match '^(\.github/|ci/|scripts/|toolshed/|conftest\.py$|pyproject\.toml$|pixi\.(toml|lock)$|pytest\.ini$|ruff\.toml$)')"
+            echo "merge_base=${base}"
           } >> "$GITHUB_OUTPUT"
 
       - name: Compose gating outputs
@@ -228,6 +230,89 @@ jobs:
             echo "test_pathfinder=${test_pathfinder}"
           } >> "$GITHUB_OUTPUT"
 
+  api-check-core-vs-release:
+    name: API check (cuda_core vs. latest release)
+    if: >-
+      ${{ !fromJSON(needs.should-skip.outputs.skip) &&
+          fromJSON(needs.detect-changes.outputs.core) }}
+    runs-on: ubuntu-latest
+    needs:
+      - should-skip
+      - detect-changes
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        with:
+          fetch-depth: 1
+          filter: blob:none
+
+      - name: Find latest release tag
+        id: latest-tag
+        shell: bash --noprofile --norc -euo pipefail {0}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # --paginate fetches all pages; jq outputs one name per line per page;
+          # head -1 takes the first (newest) match since GitHub returns tags
+          # newest-first. Fails hard if no cuda-core-v* tag is found.
+          tag="$(gh api "repos/$GITHUB_REPOSITORY/tags" --paginate \
+            --jq '.[] | select(.name | startswith("cuda-core-v")) | .name' \
+            | head -1)"
+          if [[ -z "${tag}" ]]; then
+            echo "::error::No cuda-core-v* tag found in the repository." >&2
+            exit 1
+          fi
+          echo "tag=${tag}" >> "$GITHUB_OUTPUT"
+
+      - name: Fetch release tag
+        shell: bash --noprofile --norc -euo pipefail {0}
+        run: |
+          git fetch --depth=1 --filter=blob:none origin \
+            "refs/tags/${{ steps.latest-tag.outputs.tag }}:refs/tags/${{ steps.latest-tag.outputs.tag }}"
+
+      - name: Check cuda_core public API
+        id: griffe
+        uses: ./.github/actions/griffe-api-check
+        with:
+          package-name: cuda.core
+          package-dir: cuda_core
+          merge-base: ${{ steps.latest-tag.outputs.tag }}
+
+  api-check-core-vs-base:
+    name: API check (cuda_core vs. merge base)
+    if: >-
+      ${{ startsWith(github.ref_name, 'pull-request/') &&
+          !fromJSON(needs.should-skip.outputs.skip) &&
+          fromJSON(needs.detect-changes.outputs.core) }}
+    runs-on: ubuntu-latest
+    needs:
+      - should-skip
+      - detect-changes
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        with:
+          fetch-depth: 1
+          filter: blob:none
+
+      - name: Fetch merge base commit
+        shell: bash --noprofile --norc -euo pipefail {0}
+        run: |
+          git fetch --depth=1 --filter=blob:none origin \
+            "${{ needs.detect-changes.outputs.pr_merge_base }}"
+
+      - name: Check cuda_core public API
+        id: griffe
+        uses: ./.github/actions/griffe-api-check
+        with:
+          package-name: cuda.core
+          package-dir: cuda_core
+          merge-base: ${{ needs.detect-changes.outputs.pr_merge_base }}
+
   # NOTE: Build jobs are intentionally split by platform rather than using a single
   # matrix. This allows each test job to depend only on its corresponding build,
   # so faster platforms can proceed through build & test without waiting for slower

.github/workflows/release.yml

@@ -158,6 +158,8 @@ jobs:
     steps:
       - name: Checkout Source
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        with:
+          ref: ${{ inputs.git-tag }}
 
       - name: Set up Python
         uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6.3.0

CONTRIBUTING.md

@@ -19,6 +19,10 @@ Thank you for your interest in contributing to CUDA Python! Based on the type of
 
 - [Contributing to CUDA Python](#contributing-to-cuda-python)
   - [Table of Contents](#table-of-contents)
+  - [Cloning the repository](#cloning-the-repository)
+    - [Recommended clone](#recommended-clone)
+    - [Fixing an existing clone](#fixing-an-existing-clone)
+    - [Symptoms of a bad clone](#symptoms-of-a-bad-clone)
   - [Type stubs for cuda.core](#type-stubs-for-cudacore)
   - [Pre-commit](#pre-commit)
   - [Signing Your Work](#signing-your-work)
@@ -34,6 +38,94 @@ Thank you for your interest in contributing to CUDA Python! Based on the type of
   - [Code coverage](#code-coverage)
 
 
+## Cloning the repository
+
+Every package in this repository derives its version from git tags using
+[`setuptools-scm`](https://setuptools-scm.readthedocs.io/), so **how you clone
+determines whether you can build at all, and whether the version you build is
+correct.** Each package matches its own tag prefix:
+
+| Package | Tag pattern |
+| --- | --- |
+| `cuda-bindings`, `cuda-python` | `v*` (e.g. `v13.3.1`) |
+| `cuda-core` | `cuda-core-v*` (e.g. `cuda-core-v1.1.0`) |
+| `cuda-pathfinder` | `cuda-pathfinder-v*` (e.g. `cuda-pathfinder-v1.6.0`) |
+
+Each package sets `root = ".."` in its `[tool.setuptools_scm]` table, meaning the
+version is read from the *repository root* rather than the package directory. A
+working build therefore needs all of the following:
+
+1. **A real git clone.** Source zips and GitHub "Download ZIP" archives have no
+   git metadata and the build fails outright. (Tarballs produced by
+   `git archive` do work, thanks to the `.git_archival.txt` substitutions
+   configured in `.gitattributes`.)
+2. **The full repository**, not just the package subdirectory, because the
+   version lookup walks up to the repository root.
+3. **Tags, reaching back at least as far as the most recent tag** matching the
+   package you are building. `git describe` needs to find that tag; the history
+   between it and your checkout must be present too.
+
+### Recommended clone
+
+The default `git clone` gives you everything you need:
+
+```console
+$ git clone https://github.com/NVIDIA/cuda-python.git
+```
+
+
+
+### Fixing an existing clone
+
+If you already have a shallow clone:
+
+```console
+$ git fetch --unshallow --tags
+```
+
+If you are working from a personal fork, your fork's tags stop tracking upstream
+the moment new releases are cut, which silently yields a stale version. Fetch
+tags from upstream directly:
+
+```console
+$ git remote add upstream https://github.com/NVIDIA/cuda-python.git
+$ git fetch --tags upstream
+```
+
+Keep doing this periodically — a fork that was correct when you created it will
+drift.
+
+### Symptoms of a bad clone
+
+Only case 3 below reports an error. The first two fail *silently*, producing a
+wrong version that surfaces much later as a confusing dependency-resolution or
+version-check failure:
+
+1. **No tags reachable.** The build succeeds and produces a version starting at
+   `0.1.dev`: a `--depth 1` clone yields `0.1.dev1+g0d22cb444`, a full clone made
+   with `--no-tags` yields `0.1.dev2114+g0d22cb444`. Installing `cuda-python`
+   built this way then fails, because its `install_requires` pins
+   `cuda-bindings` to that same bogus version.
+2. **Stale tags** (a fork that has not fetched upstream in a while): you get a
+   plausible-looking but wrong version, e.g. `13.0.4.dev650+g0d22cb44` when the
+   real latest tag is `v13.3.1`. Nothing warns you. Note there is no leading
+   `v` — the tag prefix is stripped by `tag_regex`.
+3. **No git metadata** (source zip): the build fails with
+   `LookupError: setuptools-scm was unable to detect version`.
+
+As a last resort — for example when building inside a container that has no git
+history — you can bypass the lookup entirely:
+
+```console
+$ SETUPTOOLS_SCM_PRETEND_VERSION_FOR_CUDA_CORE=1.1.0 pip install ./cuda_core
+```
+
+The environment variable is suffixed with the distribution name, uppercased with
+hyphens replaced by underscores: `..._FOR_CUDA_BINDINGS`, `..._FOR_CUDA_CORE`,
+`..._FOR_CUDA_PATHFINDER`, `..._FOR_CUDA_PYTHON`. Use this only when you
+genuinely cannot provide tags; it is not a substitute for a correct clone.
+
+
 ## Type stubs for cuda.core
 
 `cuda.core` is a PEP 561-compliant package: it ships a `py.typed` marker and

cuda_bindings/docs/source/install.rst

@@ -120,11 +120,14 @@ Requirements
 
 * CUDA Toolkit headers[^1]
 * CUDA Runtime static library[^2]
+* A git clone of the repository that includes tags[^3]
 
 [^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.
 
 [^2]: The CUDA Runtime static library (``libcudart_static.a`` on Linux, ``cudart_static.lib`` on Windows) is part of the CUDA Toolkit. If using conda packages, it is contained in the ``cuda-cudart-static`` package.
 
+[^3]: The version is derived from git tags via ``setuptools-scm``, so the clone must include tags reaching back to at least the latest ``v*`` tag. Clone with ``git clone https://github.com/NVIDIA/cuda-python.git``; do not use ``--depth`` or ``--no-tags``, since a shallow clone builds without error but produces a bogus version such as ``0.1.dev1+g0d22cb444``. See `Cloning the repository <https://github.com/NVIDIA/cuda-python/blob/main/CONTRIBUTING.md>`_ for details and recovery steps.
+
 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_PATH`` (or ``CUDA_HOME``) environment variable to specify the location of your headers. If both are set, ``CUDA_PATH`` takes precedence. For example, if your headers are located in ``/usr/local/cuda/include``, then you should set ``CUDA_PATH`` with:
 
 .. code-block:: console

cuda_core/build_hooks.py

@@ -17,6 +17,7 @@
 from pathlib import Path
 
 from Cython.Build import cythonize
+from Cython.Compiler import Options as _CythonOptions
 from setuptools import Extension
 from setuptools import build_meta as _build_meta
 
@@ -212,6 +213,7 @@ def get_sources(mod_name):
     nthreads = int(os.environ.get("CUDA_PYTHON_PARALLEL_LEVEL", os.cpu_count() // 2))
     compile_time_env = {"CUDA_CORE_BUILD_MAJOR": int(_determine_cuda_major_version())}
     compiler_directives = {"embedsignature": True, "warn.deprecated.IF": False, "freethreading_compatible": True}
+    _CythonOptions.warning_errors = True
     if COMPILE_FOR_COVERAGE:
         compiler_directives["linetrace"] = True
     _extensions = cythonize(

cuda_core/cuda/core/__init__.py

@@ -69,45 +69,51 @@ class _PatchedProperty(metaclass=_PatchedPropMeta):
 
 
 from cuda.core import checkpoint, system, utils
-from cuda.core._context import Context, ContextOptions
-from cuda.core._device import Device
-from cuda.core._device_resources import (
-    DeviceResources,
-    SMResource,
-    SMResourceOptions,
-    WorkqueueResource,
-    WorkqueueResourceOptions,
-)
-from cuda.core._event import Event, EventOptions
-from cuda.core._graphics import GraphicsResource
-from cuda.core._host import Host
-from cuda.core._launch_config import LaunchConfig
-from cuda.core._launcher import launch
-from cuda.core._linker import Linker, LinkerOptions
-from cuda.core._memory import (
-    Buffer,
-    DeviceMemoryResource,
-    DeviceMemoryResourceOptions,
-    GraphMemoryResource,
-    LegacyPinnedMemoryResource,
-    ManagedBuffer,
-    ManagedMemoryResource,
-    ManagedMemoryResourceOptions,
-    MemoryResource,
-    PinnedMemoryResource,
-    PinnedMemoryResourceOptions,
-    VirtualMemoryResource,
-    VirtualMemoryResourceOptions,
-)
-from cuda.core._module import Kernel, ObjectCode
-from cuda.core._program import Program, ProgramOptions
-from cuda.core._stream import (
-    LEGACY_DEFAULT_STREAM,
-    PER_THREAD_DEFAULT_STREAM,
-    Stream,
-    StreamOptions,
-)
-from cuda.core._tensor_map import TensorMapDescriptor, TensorMapDescriptorOptions
+from cuda.core._context import *
+from cuda.core._context import __all__ as _context_all
+from cuda.core._device import *
+from cuda.core._device import __all__ as _device_all
+from cuda.core._device_resources import *
+from cuda.core._device_resources import __all__ as _device_resources_all
+from cuda.core._event import *
+from cuda.core._event import __all__ as _event_all
+from cuda.core._graphics import *
+from cuda.core._graphics import __all__ as _graphics_all
+from cuda.core._host import *
+from cuda.core._host import __all__ as _host_all
+from cuda.core._launch_config import *
+from cuda.core._launch_config import __all__ as _launch_config_all
+from cuda.core._launcher import *
+from cuda.core._launcher import __all__ as _launcher_all
+from cuda.core._linker import *
+from cuda.core._linker import __all__ as _linker_all
+from cuda.core._memory import *
+from cuda.core._memory import __all__ as _memory_all
+from cuda.core._module import *
+from cuda.core._module import __all__ as _module_all
+from cuda.core._program import *
+from cuda.core._program import __all__ as _program_all
+from cuda.core._stream import *
+from cuda.core._stream import __all__ as _stream_all
+from cuda.core._tensor_map import *
+from cuda.core._tensor_map import __all__ as _tensor_map_all
+
+__all__ = [
+    *_context_all,
+    *_device_all,
+    *_device_resources_all,
+    *_event_all,
+    *_graphics_all,
+    *_host_all,
+    *_launch_config_all,
+    *_launcher_all,
+    *_linker_all,
+    *_memory_all,
+    *_module_all,
+    *_program_all,
+    *_stream_all,
+    *_tensor_map_all,
+]
 
 # isort: split
 # Texture/surface types live under the cuda.core.texture namespace (not the