Skip to content

Commit 6ba9004

Browse files
Andy-Jostclaude
andcommitted
cuda-bindings header check at build; final floor messages; bounds spelled <next major> (NVIDIA#2783)
- cuda_bindings/build_hooks.py: before cythonize, compare the toolkit's cuda.h CUDA_VERSION with the one the sources were generated from (cydriver.pxd). A mismatch fails with a message that names the resolved cuda.h, both versions, the run-time compatibility, and the two remedies. Tests in cuda_bindings/tests/test_build_hooks.py; install page and 13.5.0 release note. - cuda.core build-time and import-time messages: name the resolved cuda.h, state what is needed and what was found, say that the rule does not constrain the CUDA driver or toolkit at run time, and link the support policy. - Review follow-ups: the cu12/cu13 extras read `>=<floor>,<<next major>`; the floor reader accepts `<N+1` or `==N.*` and checks that the bounds confine cuda-bindings to major N; bindings_requirement() takes an upper bound; the pip commands in the messages use the same form. Two wording fixes in support.rst. Co-Authored-By: Claude Fable 5.1 <[email protected]>
1 parent a37c10a commit 6ba9004

13 files changed

Lines changed: 282 additions & 60 deletions

File tree

‎cuda_bindings/AGENTS.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,9 @@ the `legacy_tests` subdirectory.
5151

5252
- `CUDA_HOME` or `CUDA_PATH` must point to a valid CUDA Toolkit for source
5353
builds.
54+
- The toolkit's `cuda.h` must have the major.minor the generated sources came
55+
from (`CUDA_VERSION` in `cuda/bindings/cydriver.pxd`). `build_hooks.py`
56+
checks this before cythonize and fails with a message that names both.
5457
- `CUDA_PYTHON_PARALLEL_LEVEL` controls build parallelism.
5558
- Runtime behavior is affected by
5659
`CUDA_PYTHON_CUDA_PER_THREAD_DEFAULT_STREAM` and

‎cuda_bindings/build_hooks.py‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
import functools
1313
import glob
1414
import os
15+
import re
1516
import shutil
1617
import sys
1718
import sysconfig
@@ -33,6 +34,13 @@
3334
# Populated by _build_cuda_bindings(); consumed by setup.py.
3435
_extensions = None
3536

37+
# The generated sources declare the types and functions of one CUDA header set;
38+
# cydriver.pxd records which. The install docs state the resulting build rule.
39+
_CYDRIVER_PXD = Path(__file__).resolve().parent / "cuda" / "bindings" / "cydriver.pxd"
40+
_GENERATED_VERSION_RE = re.compile(r"^cdef enum:\s*CUDA_VERSION\s*=\s*(\d+)\s*$")
41+
_CUDA_H_VERSION_RE = re.compile(r"^#\s*define\s+CUDA_VERSION\s+(\d+)\s*$")
42+
_INSTALL_URL = "https://nvidia.github.io/cuda-python/cuda-bindings/latest/install.html#installing-from-source"
43+
3644

3745
# Please keep in sync with the copy in cuda_core/build_hooks.py.
3846
def _import_get_cuda_path_or_home():
@@ -80,6 +88,72 @@ def _get_cuda_path() -> str:
8088
return cuda_path
8189

8290

91+
# -----------------------------------------------------------------------
92+
# CUDA header check
93+
94+
95+
def _cuda_h_path(cuda_path: str) -> str:
96+
"""The cuda.h under cuda_path, with symlinks such as /usr/local/cuda resolved for messages."""
97+
return os.path.realpath(os.path.join(cuda_path, "include", "cuda.h"))
98+
99+
100+
def _read_version_macro(path: str, pattern: re.Pattern) -> int | None:
101+
"""The integer on the first line of ``path`` that matches ``pattern``, or None if no line does."""
102+
with open(path, encoding="utf-8") as f:
103+
for line in f:
104+
m = pattern.match(line)
105+
if m:
106+
return int(m.group(1))
107+
return None
108+
109+
110+
def _read_cuda_h_version(cuda_path: str) -> int:
111+
"""The CUDA_VERSION macro (e.g. 13040 for 13.4) of the cuda.h under cuda_path."""
112+
cuda_h = _cuda_h_path(cuda_path)
113+
try:
114+
version = _read_version_macro(cuda_h, _CUDA_H_VERSION_RE)
115+
except OSError:
116+
version = None
117+
if version is None:
118+
raise RuntimeError(
119+
f"Cannot read CUDA_VERSION from {cuda_h}. "
120+
"Ensure CUDA_PATH or CUDA_HOME points to a CUDA Toolkit with include/cuda.h."
121+
)
122+
return version
123+
124+
125+
def _generated_cuda_version() -> int:
126+
"""The CUDA_VERSION of the headers this source tree was generated from (cuda/bindings/cydriver.pxd)."""
127+
version = _read_version_macro(str(_CYDRIVER_PXD), _GENERATED_VERSION_RE)
128+
if version is None:
129+
raise RuntimeError(f"Cannot read CUDA_VERSION from {_CYDRIVER_PXD}")
130+
return version
131+
132+
133+
def _major_minor(cuda_version: int) -> str:
134+
"""13040 -> \"13.4\"."""
135+
return f"{cuda_version // 1000}.{cuda_version // 10 % 100}"
136+
137+
138+
def _check_cuda_headers(cuda_path: str) -> None:
139+
"""Reject a toolkit whose cuda.h is not the major.minor this source tree was generated from.
140+
141+
Against another minor, the C++ compile fails with a long list of
142+
redefinition and undeclared-type errors that do not name the cause
143+
(https://github.com/NVIDIA/cuda-python/issues/2783). Runs before
144+
cythonize, which is the first step that touches the source tree.
145+
"""
146+
generated = _generated_cuda_version()
147+
needed, found = _major_minor(generated), _major_minor(_read_cuda_h_version(cuda_path))
148+
if found != needed:
149+
raise RuntimeError(
150+
f"This cuda-bindings source tree needs CUDA {needed} headers, but {_cuda_h_path(cuda_path)} is "
151+
f"CUDA {found}. This is a build-time requirement only: at run time cuda-bindings supports any "
152+
f"CUDA {generated // 1000}.x toolkit, see {_INSTALL_URL}. Point CUDA_PATH or CUDA_HOME at a "
153+
f"CUDA {needed} toolkit, or build from cuda-bindings {found}.x sources."
154+
)
155+
156+
83157
# -----------------------------------------------------------------------
84158
# Extension preparation helpers
85159

@@ -142,6 +216,7 @@ def _build_cuda_bindings(debug=False):
142216
global _extensions
143217

144218
cuda_path = _get_cuda_path()
219+
_check_cuda_headers(cuda_path)
145220

146221
if os.environ.get("PARALLEL_LEVEL") is not None:
147222
warn(

‎cuda_bindings/docs/source/install.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,7 @@ Requirements
128128

129129
[^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.
130130

131-
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:
131+
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. The build checks the header before it compiles anything; a mismatch stops it with a message that names the ``cuda.h`` it found and the version this source tree needs. 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:
132132

133133
.. code-block:: console
134134

‎cuda_bindings/docs/source/release/13.5.0-notes.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -301,6 +301,7 @@ Enhancements
301301
- ``nvvm.add_module_to_program``, ``nvvm.lazy_add_module_to_program``, ``nvvm.get_compiled_result``, ``nvvm.get_program_log`` (``buffer``)
302302
- For all ``cuda-bindings`` APIs, functions that accept a struct wrapper will accept the struct wrapper directly, rather than requiring getting the ``.ptr`` property.
303303
- Creating class instances in ``cuda-bindings`` should now be faster in most cases, because it requires 1 heap allocation rather than 2.
304+
- A source build now checks, before it compiles anything, that the CUDA Toolkit's ``cuda.h`` has the major.minor this source tree was generated from. A mismatch stops the build with a message that names the header found and the version needed. It used to surface as a long list of C++ redefinition errors.
304305

305306
Behavior changes
306307
----------------
Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
"""build_hooks.py: the CUDA header check that runs before cythonize.
5+
6+
A cuda-bindings source tree is generated from one CUDA header set and compiles
7+
only against a toolkit of that major.minor; against another minor the C++
8+
compile fails with redefinition errors that do not name the cause. The check
9+
reads both versions and fails early with a message that does. No GPU needed.
10+
11+
build_hooks.py is a PEP 517 backend, not an installed module, so it is loaded
12+
from source. It imports setuptools at the top; the ``test`` extra provides it.
13+
"""
14+
15+
import importlib.util
16+
import os
17+
from pathlib import Path
18+
19+
import pytest
20+
import setuptools # noqa: F401
21+
22+
# Don't call .resolve(): a symlinked checkout would make parents[1] point elsewhere.
23+
BUILD_HOOKS = Path(__file__).parents[1] / "build_hooks.py"
24+
25+
26+
@pytest.fixture(scope="module")
27+
def build_hooks():
28+
if not BUILD_HOOKS.is_file():
29+
pytest.skip(f"{BUILD_HOOKS} is not in this tree; these tests need the source checkout")
30+
spec = importlib.util.spec_from_file_location("cuda_bindings_build_hooks", BUILD_HOOKS)
31+
module = importlib.util.module_from_spec(spec)
32+
spec.loader.exec_module(module)
33+
return module
34+
35+
36+
def _write_cuda_h(tmp_path, cuda_version):
37+
include = tmp_path / "include"
38+
include.mkdir(exist_ok=True)
39+
(include / "cuda.h").write_text(f"#define CUDA_VERSION {cuda_version}\n", encoding="utf-8")
40+
return str(tmp_path)
41+
42+
43+
@pytest.mark.agent_authored(model="claude-fable-5-1")
44+
def test_generated_header_version_is_read_from_cydriver_pxd(build_hooks):
45+
generated = build_hooks._generated_cuda_version()
46+
assert generated // 1000 in (12, 13)
47+
assert build_hooks._major_minor(13040) == "13.4"
48+
assert build_hooks._major_minor(12090) == "12.9"
49+
50+
51+
@pytest.mark.agent_authored(model="claude-fable-5-1")
52+
def test_a_header_of_the_generated_major_minor_passes(build_hooks, tmp_path):
53+
generated = build_hooks._generated_cuda_version()
54+
build_hooks._check_cuda_headers(_write_cuda_h(tmp_path, generated))
55+
# Only major.minor matters; the last digit (13041) is a toolkit patch.
56+
build_hooks._check_cuda_headers(_write_cuda_h(tmp_path, generated + 1))
57+
58+
59+
@pytest.mark.agent_authored(model="claude-fable-5-1")
60+
@pytest.mark.parametrize("delta", [-10, 10, -1000, 1000])
61+
def test_another_header_fails_and_names_both_versions(build_hooks, tmp_path, delta):
62+
generated = build_hooks._generated_cuda_version()
63+
cuda_path = _write_cuda_h(tmp_path, generated + delta)
64+
with pytest.raises(RuntimeError) as excinfo:
65+
build_hooks._check_cuda_headers(cuda_path)
66+
message = str(excinfo.value)
67+
needed, found = build_hooks._major_minor(generated), build_hooks._major_minor(generated + delta)
68+
assert message.startswith(f"This cuda-bindings source tree needs CUDA {needed} headers, but ")
69+
assert os.path.realpath(os.path.join(cuda_path, "include", "cuda.h")) in message # the resolved path
70+
assert f" is CUDA {found}. This is a build-time requirement only" in message
71+
assert build_hooks._INSTALL_URL in message
72+
assert message.endswith(
73+
f"Point CUDA_PATH or CUDA_HOME at a CUDA {needed} toolkit, or build from cuda-bindings {found}.x sources."
74+
)
75+
76+
77+
@pytest.mark.agent_authored(model="claude-fable-5-1")
78+
def test_an_unreadable_cuda_h_is_a_clear_error(build_hooks, tmp_path):
79+
with pytest.raises(RuntimeError, match=r"Cannot read CUDA_VERSION from .*cuda\.h"):
80+
build_hooks._check_cuda_headers(str(tmp_path)) # no include/cuda.h
81+
(tmp_path / "include").mkdir()
82+
(tmp_path / "include" / "cuda.h").write_text("/* no CUDA_VERSION macro */\n", encoding="utf-8")
83+
with pytest.raises(RuntimeError, match=r"Cannot read CUDA_VERSION from .*cuda\.h"):
84+
build_hooks._check_cuda_headers(str(tmp_path))
85+
86+
87+
@pytest.mark.agent_authored(model="claude-fable-5-1")
88+
def test_the_build_checks_the_header_before_it_touches_the_tree(build_hooks, tmp_path, monkeypatch):
89+
pytest.importorskip("Cython") # _build_cuda_bindings imports it first
90+
cuda_path = _write_cuda_h(tmp_path, build_hooks._generated_cuda_version() + 10)
91+
monkeypatch.setattr(build_hooks, "_get_cuda_path", lambda: cuda_path)
92+
93+
def not_reached():
94+
raise AssertionError("the header check must run before the source tree is modified")
95+
96+
monkeypatch.setattr(build_hooks, "_rename_architecture_specific_files", not_reached)
97+
with pytest.raises(RuntimeError, match="source tree needs CUDA .* headers"):
98+
build_hooks._build_cuda_bindings()

‎cuda_core/AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ This file describes `cuda_core`, the high-level Pythonic CUDA subpackage in the
3434
- `cuda_core` requires `cuda.bindings` at or above a per-major *floor* at build
3535
and run time, and a `cuda.h` of the same major.minor as that `cuda.bindings`
3636
at build time (NVIDIA/cuda-python#2783). The floors are declared once, by the
37-
`cu12`/`cu13` extras in `pyproject.toml` (`cuda-bindings[all]>=<floor>,==<major>.*`);
37+
`cu12`/`cu13` extras in `pyproject.toml` (`cuda-bindings[all]>=<floor>,<<next major>`);
3838
`build_hooks.py`, the import-time check in `cuda/core/__init__.py`, the docs
3939
and CI read them from there through `cuda/core/_bindings_floor.py`. The C++
4040
branches on `CUDA_CORE_BUILD_MAJOR` only; whether a feature is available at

‎cuda_core/build_hooks.py‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -176,9 +176,14 @@ def _floor_for(cuda_major) -> tuple:
176176
return floors[major]
177177

178178

179+
def _cuda_h_path(cuda_path: str) -> str:
180+
"""The cuda.h under cuda_path, with symlinks such as /usr/local/cuda resolved for messages."""
181+
return os.path.realpath(os.path.join(cuda_path, "include", "cuda.h"))
182+
183+
179184
def _read_cuda_h_version(cuda_path: str) -> int:
180185
"""The CUDA_VERSION macro (e.g. 13040 for 13.4) of the cuda.h under cuda_path."""
181-
cuda_h = os.path.join(cuda_path, "include", "cuda.h")
186+
cuda_h = _cuda_h_path(cuda_path)
182187
try:
183188
with open(cuda_h, encoding="utf-8") as f:
184189
for line in f:
@@ -281,12 +286,13 @@ def _check_build_configuration(cuda_path: str, cuda_major: str) -> None:
281286
header = floor.header_minor(cuda_version)
282287
generated_from = floor.header_minor(bindings_cuda_version)
283288
if header != generated_from:
289+
needed, found = f"{generated_from[0]}.{generated_from[1]}", f"{header[0]}.{header[1]}"
284290
raise RuntimeError(
285-
f"cuda.h under {cuda_path} is CUDA {header[0]}.{header[1]}, but the installed cuda-bindings "
286-
f"{bindings_version} was generated from CUDA {generated_from[0]}.{generated_from[1]} headers. "
287-
"cuda.core must be built against the cuda.h its cuda-bindings was generated from. Point "
288-
"CUDA_PATH or CUDA_HOME at that CUDA Toolkit, or install a matching cuda-bindings (for an "
289-
"isolated build, constrain it with PIP_CONSTRAINT or build with --no-build-isolation)."
291+
f"cuda.core needs CUDA {needed} headers to build with the installed cuda-bindings {bindings_version}, "
292+
f"but {_cuda_h_path(cuda_path)} is CUDA {found}. This is a build-time requirement only: at run time "
293+
f"cuda.core supports older CUDA {major}.x drivers and toolkits, see {floor.SUPPORT_URL}. Point "
294+
f"CUDA_PATH or CUDA_HOME at a CUDA {needed} toolkit, or install cuda-bindings {found}.x. For an "
295+
"isolated build, constrain cuda-bindings with PIP_CONSTRAINT or build with --no-build-isolation."
290296
)
291297
print(f"Build configuration: CUDA {header[0]}.{header[1]} headers, cuda-bindings {bindings_version}")
292298
_write_build_info(major, cuda_version, floor_triple, bindings_version)
@@ -665,7 +671,7 @@ def _get_cuda_bindings_require():
665671
return [floor.bindings_requirement(floor_triple)]
666672
if header[0] != floor_triple[0] or header[1] < floor_triple[1]:
667673
return [floor.bindings_requirement(floor_triple)]
668-
return [f"{floor.bindings_requirement(floor_triple)},<{header[0]}.{header[1] + 1}"]
674+
return [floor.bindings_requirement(floor_triple, below=(header[0], header[1] + 1))]
669675

670676

671677
def get_requires_for_build_editable(config_settings=None):

0 commit comments

Comments
 (0)