Skip to content

Commit ab980a9

Browse files
committed
cuda.core: declare the cuda-bindings floor once, in the pyproject extras (NVIDIA#2783)
The floor of each CUDA major was typed in three places: a table in cuda/core/_bindings_floor.py, the cu12/cu13 extras in pyproject.toml, and the support-policy table in the docs, kept in step by tests that only ran in the GPU test jobs. The extras are now the single declaration, in the form `cuda-bindings[all]>=<floor>,==<major>.*`, and everything derives from them: - _bindings_floor.py keeps the logic only: floors_from_extras() parses the [project.optional-dependencies] table strictly (a malformed extra fails instead of shifting the floor), plus the version helpers and the import-time check, which now takes the build's recorded floor. - build_hooks.py reads pyproject.toml (tomllib; tomli on 3.10, added to build-system.requires) for the build-time check, the dynamic build requirement and -DCUDA_CORE_MIN_CUDA_VERSION, and records the floor in the generated _build_info.py, which cuda/core/__init__.py already reads. __init__.py no longer hard-codes the supported majors. - ci/tools/cuda_core_bindings_floor.py reads the floor out of the wheel's _build_info.py (per major in the merged wheel) instead of the table. - docs/source/conf.py defines |cuda-bindings-floor-cu12| and |cuda-bindings-floor-cu13| from pyproject.toml; support.rst uses them and labels the row with |release|. The stale cuda-bindings minimums in api_nvml.rst are gone: cuda.core.system has no requirement beyond the floor. - toolshed/check_cuda_core_bindings_floor.py, a new pre-commit hook, checks the two constraints that cannot be derived: ci/versions.yml must build each major against a toolkit of the floor's major.minor, and no documentation page (release notes excepted) may spell a floor out by hand. tests/test_bindings_floor.py runs the same checks. - AGENTS.md documents the coupling and a "Bumping the cuda-bindings floor" checklist.
1 parent b06cc7c commit ab980a9

14 files changed

Lines changed: 592 additions & 168 deletions

‎.pre-commit-config.yaml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,15 @@ repos:
4242
pass_filenames: false
4343
verbose: true
4444

45+
- id: check-cuda-core-bindings-floor
46+
name: Check the cuda-bindings floor against ci/versions.yml and the docs
47+
entry: python ./toolshed/check_cuda_core_bindings_floor.py
48+
language: python
49+
files: ^(cuda_core/pyproject\.toml|ci/versions\.yml|cuda_core/cuda/core/_bindings_floor\.py|cuda_core/docs/source/.*\.rst|toolshed/check_cuda_core_bindings_floor\.py)$
50+
pass_filenames: false
51+
additional_dependencies:
52+
- "tomli>=1.1.0; python_version < '3.11'"
53+
4554
- id: check-spdx
4655
name: Check SPDX Headers
4756
entry: python ./toolshed/check_spdx.py

‎ci/tools/cuda_core_bindings_floor.py‎

Lines changed: 12 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,9 @@
1414
from the checkout, so a nightly job that tests a wheel built from another
1515
commit reads that wheel's floor.
1616
17-
The wheel carries the import-free module cuda/core/_bindings_floor.py, at top
18-
level in a single-major build and under cuda/core/cu<major>/ in the merged
19-
wheel; this script reads the CUDA_BINDINGS_FLOOR literal out of it (without
20-
running the module) and prints the entry for `major` as a dotted version.
17+
Each build records its floor in the generated cuda/core/_build_info.py (at top
18+
level in a single-major build, under cuda/core/cu<major>/ in the merged wheel);
19+
this script reads the CUDA_BINDINGS_FLOOR literal out of it without running it.
2120
"""
2221

2322
from __future__ import annotations
@@ -28,28 +27,27 @@
2827
import zipfile
2928
from pathlib import Path
3029

31-
MODULE = "_bindings_floor.py"
30+
MODULE = "_build_info.py"
3231

3332

34-
def floors_from_source(source: str) -> dict[int, tuple[int, int, int]]:
35-
"""The CUDA_BINDINGS_FLOOR literal of _bindings_floor.py, parsed without executing it."""
33+
def _literal(source: str, name: str):
34+
"""The literal assigned to `name` at module level of `source`, parsed without executing it."""
3635
for node in ast.parse(source, MODULE).body:
3736
if isinstance(node, ast.AnnAssign):
3837
targets = [node.target]
3938
elif isinstance(node, ast.Assign):
4039
targets = node.targets
4140
else:
4241
continue
43-
if node.value is not None and any(isinstance(t, ast.Name) and t.id == "CUDA_BINDINGS_FLOOR" for t in targets):
42+
if node.value is not None and any(isinstance(t, ast.Name) and t.id == name for t in targets):
4443
return ast.literal_eval(node.value)
45-
raise SystemExit(f"{MODULE} does not assign CUDA_BINDINGS_FLOOR")
44+
raise SystemExit(f"{MODULE} does not assign {name}")
4645

4746

4847
def floor_from_source(source: str, major: int) -> str:
49-
floors = floors_from_source(source)
50-
if major not in floors:
51-
raise SystemExit(f"CUDA {major} is not a supported major (floors: {sorted(floors)})")
52-
return ".".join(str(part) for part in floors[major])
48+
if _literal(source, "CUDA_MAJOR") != major:
49+
raise SystemExit(f"{MODULE} records a CUDA {_literal(source, 'CUDA_MAJOR')} build, not CUDA {major}")
50+
return ".".join(str(part) for part in _literal(source, "CUDA_BINDINGS_FLOOR"))
5351

5452

5553
def floor_from_wheel(wheel: Path, major: int) -> str:
@@ -58,7 +56,7 @@ def floor_from_wheel(wheel: Path, major: int) -> str:
5856
for candidate in (f"cuda/core/cu{major}/{MODULE}", f"cuda/core/{MODULE}"):
5957
if candidate in names:
6058
return floor_from_source(zf.read(candidate).decode("utf-8"), major)
61-
raise SystemExit(f"{wheel.name} contains no {MODULE}; is it a cuda-core wheel?")
59+
raise SystemExit(f"{wheel.name} contains no build for CUDA {major} (no {MODULE}); is it a cuda-core wheel?")
6260

6361

6462
def main(argv: list[str] | None = None) -> int:

‎ci/tools/tests/test_cuda_core_bindings_floor.py‎

Lines changed: 32 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,6 @@
99
import pytest
1010

1111
TOOLS = Path(__file__).resolve().parent.parent
12-
REPO = TOOLS.parent.parent
13-
FLOOR_MODULE = REPO / "cuda_core" / "cuda" / "core" / "_bindings_floor.py"
1412

1513

1614
def _load(name, path):
@@ -21,50 +19,64 @@ def _load(name, path):
2119

2220

2321
tool = _load("cuda_core_bindings_floor", TOOLS / "cuda_core_bindings_floor.py")
24-
floor_module = _load("cuda_core_bindings_floor_module", FLOOR_MODULE)
2522

23+
FLOORS = {12: (12, 9, 8), 13: (13, 4, 1)}
2624

27-
def _expected(major):
28-
return floor_module.format_version(floor_module.CUDA_BINDINGS_FLOOR[major])
25+
26+
def _build_info(major):
27+
floor = FLOORS[major]
28+
return (
29+
"# Generated by build_hooks.py at build time. Do not edit or commit.\n"
30+
f"CUDA_MAJOR = {major}\n"
31+
f"CUDA_VERSION = {major * 1000 + floor[1] * 10} # the cuda.h this build compiled against\n"
32+
f"CUDA_BINDINGS_FLOOR = {floor!r}\n"
33+
f"CUDA_BINDINGS_BUILD_VERSION = '{major}.{floor[1]}.{floor[2]}'\n"
34+
)
2935

3036

3137
def _wheel(tmp_path, entries):
3238
path = tmp_path / "cuda_core-1.3.0-cp312-cp312-linux_x86_64.whl"
3339
with zipfile.ZipFile(path, "w") as zf:
34-
for name in entries:
35-
zf.writestr(name, FLOOR_MODULE.read_text(encoding="utf-8"))
40+
for name, major in entries.items():
41+
zf.writestr(name, _build_info(major))
3642
return path
3743

3844

3945
@pytest.mark.agent_authored(model="claude-fable-5-1")
4046
@pytest.mark.parametrize("major", [12, 13])
4147
def test_reads_the_merged_wheel_layout(tmp_path, major):
42-
wheel = _wheel(tmp_path, ["cuda/core/cu12/_bindings_floor.py", "cuda/core/cu13/_bindings_floor.py"])
43-
assert tool.floor_from_wheel(wheel, major) == _expected(major)
48+
wheel = _wheel(tmp_path, {"cuda/core/cu12/_build_info.py": 12, "cuda/core/cu13/_build_info.py": 13})
49+
assert tool.floor_from_wheel(wheel, major) == ".".join(map(str, FLOORS[major]))
4450

4551

4652
@pytest.mark.agent_authored(model="claude-fable-5-1")
4753
def test_reads_a_single_major_wheel(tmp_path):
48-
wheel = _wheel(tmp_path, ["cuda/core/_bindings_floor.py"])
49-
assert tool.floor_from_wheel(wheel, 13) == _expected(13)
54+
wheel = _wheel(tmp_path, {"cuda/core/_build_info.py": 13})
55+
assert tool.floor_from_wheel(wheel, 13) == "13.4.1"
56+
57+
58+
@pytest.mark.agent_authored(model="claude-fable-5-1")
59+
def test_rejects_a_single_major_wheel_of_another_major(tmp_path):
60+
wheel = _wheel(tmp_path, {"cuda/core/_build_info.py": 13})
61+
with pytest.raises(SystemExit, match="records a CUDA 13 build, not CUDA 12"):
62+
tool.floor_from_wheel(wheel, 12)
5063

5164

5265
@pytest.mark.agent_authored(model="claude-fable-5-1")
53-
def test_rejects_a_wheel_without_the_module(tmp_path):
54-
wheel = _wheel(tmp_path, [])
55-
with pytest.raises(SystemExit, match="contains no _bindings_floor.py"):
66+
def test_rejects_a_wheel_without_the_build_record(tmp_path):
67+
wheel = _wheel(tmp_path, {})
68+
with pytest.raises(SystemExit, match="contains no build for CUDA 13"):
5669
tool.floor_from_wheel(wheel, 13)
5770

5871

5972
@pytest.mark.agent_authored(model="claude-fable-5-1")
60-
def test_rejects_an_unsupported_major(tmp_path):
61-
wheel = _wheel(tmp_path, ["cuda/core/_bindings_floor.py"])
62-
with pytest.raises(SystemExit, match="CUDA 11 is not a supported major"):
63-
tool.floor_from_wheel(wheel, 11)
73+
def test_rejects_a_build_record_without_the_floor():
74+
with pytest.raises(SystemExit, match="does not assign CUDA_BINDINGS_FLOOR"):
75+
tool.floor_from_source("CUDA_MAJOR = 13\n", 13)
6476

6577

6678
@pytest.mark.agent_authored(model="claude-fable-5-1")
6779
def test_cli_prints_the_floor(tmp_path, capsys):
68-
wheel = _wheel(tmp_path, ["cuda/core/_bindings_floor.py"])
80+
wheel = _wheel(tmp_path, {"cuda/core/_build_info.py": 13})
6981
assert tool.main(["--wheel", str(wheel), "--major", "13"]) == 0
70-
assert capsys.readouterr().out.strip() == _expected(13)
82+
assert capsys.readouterr().out.strip() == "13.4.1"

‎cuda_core/AGENTS.md‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,35 @@ This file describes `cuda_core`, the high-level Pythonic CUDA subpackage in the
3131
or CUDA headers (`CUDA_HOME`/`CUDA_PATH`) and uses it for build decisions.
3232
- Source builds require CUDA headers available through `CUDA_HOME` or
3333
`CUDA_PATH`.
34-
- `cuda_core` expects `cuda.bindings` to be present and version-compatible.
34+
- `cuda_core` requires `cuda.bindings` at or above a per-major *floor* at build
35+
and run time, and a `cuda.h` of the same major.minor as that `cuda.bindings`
36+
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>.*`);
38+
`build_hooks.py`, the import-time check in `cuda/core/__init__.py`, the docs
39+
and CI read them from there through `cuda/core/_bindings_floor.py`. The C++
40+
branches on `CUDA_CORE_BUILD_MAJOR` only; whether a feature is available at
41+
run time depends on the driver alone, never on the `cuda.bindings` version.
42+
43+
### Bumping the cuda-bindings floor
44+
45+
By policy the floor of each major is the newest `cuda-bindings` release of that
46+
major at the time of a `cuda.core` release, so the bump is a release step, not
47+
something each `cuda-bindings` minor triggers. It is also required by the first
48+
change that uses a `cuda-bindings` API newer than the old floor. To bump:
49+
50+
1. Edit the `cuda-bindings` pin in the `cu12` or `cu13` extra in
51+
`pyproject.toml`. That is the only version to type.
52+
2. Align `ci/versions.yml`: the `build` (current major) and `prev_build` (prior
53+
major) toolkit pins must share major.minor with the floors, or CI builds a
54+
configuration the build rejects. The pre-commit hook
55+
`check-cuda-core-bindings-floor` (`toolshed/check_cuda_core_bindings_floor.py`)
56+
checks this, and that no documentation page spells a floor out by hand.
57+
3. Add a "Breaking Changes" entry to the release notes naming the new floors.
58+
The support-policy table in `docs/source/support.rst` reads the floors and
59+
the release version at docs-build time; there is nothing to edit there.
60+
4. Refresh the pixi lock files if the pins moved past what they resolve.
61+
5. Pin `cuda-bindings` accordingly in the conda-forge `cuda-core` feedstock
62+
(outside this repository).
3563

3664
## Testing expectations
3765

‎cuda_core/build_hooks.py‎

Lines changed: 45 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -113,9 +113,12 @@ def _get_cuda_path() -> str:
113113
_BUILD_INFO_PATH = _PACKAGE_DIR / "_build_info.py"
114114

115115

116+
_PYPROJECT_PATH = Path(__file__).parent / "pyproject.toml"
117+
118+
116119
@functools.cache
117120
def _load_bindings_floor():
118-
"""Load cuda/core/_bindings_floor.py, the floor's single source of truth.
121+
"""Load cuda/core/_bindings_floor.py, the floor logic (reading, formatting, checking).
119122
120123
Loaded by file path: the package this backend builds is not importable
121124
during its own build, and the module is deliberately import-free.
@@ -127,6 +130,38 @@ def _load_bindings_floor():
127130
return module
128131

129132

133+
@functools.cache
134+
def _bindings_floors() -> dict:
135+
"""The cuda-bindings floor per CUDA major, from the cu<major> extras of pyproject.toml.
136+
137+
The extras are the single place the floors are declared; the build, the
138+
import-time check, the docs and CI all derive from them (see
139+
cuda/core/_bindings_floor.py). A malformed extra fails the build here.
140+
"""
141+
try:
142+
import tomllib
143+
except ModuleNotFoundError: # Python 3.10: tomli is in build-system.requires
144+
import tomli as tomllib
145+
with open(_PYPROJECT_PATH, "rb") as f:
146+
extras = tomllib.load(f)["project"]["optional-dependencies"]
147+
try:
148+
return _load_bindings_floor().floors_from_extras(extras)
149+
except ValueError as exc:
150+
raise RuntimeError(f"{_PYPROJECT_PATH}: {exc}") from exc
151+
152+
153+
def _floor_for(cuda_major) -> tuple:
154+
"""The floor of `cuda_major`, or a build error naming the supported majors."""
155+
floors = _bindings_floors()
156+
major = int(cuda_major)
157+
if major not in floors:
158+
raise RuntimeError(
159+
f"cuda.core does not support CUDA {major}; supported CUDA major versions: "
160+
f"{', '.join(str(m) for m in floors)}"
161+
)
162+
return floors[major]
163+
164+
130165
def _read_cuda_h_version(cuda_path: str) -> int:
131166
"""The CUDA_VERSION macro (e.g. 13040 for 13.4) of the cuda.h under cuda_path."""
132167
cuda_h = os.path.join(cuda_path, "include", "cuda.h")
@@ -188,8 +223,8 @@ def _check_build_configuration(cuda_path: str, cuda_major: str) -> None:
188223
"""Reject build configurations cuda.core does not support, then record the build.
189224
190225
cuda.core supports one configuration per CUDA major series: the installed
191-
cuda-bindings is at least the series' floor (cuda/core/_bindings_floor.py)
192-
and the cuda.h it compiles against has the same major.minor as that
226+
cuda-bindings is at least the series' floor (the cu<major> extra in
227+
pyproject.toml) and the cuda.h it compiles against has the same major.minor as that
193228
cuda-bindings, which is the header cuda-bindings itself was generated from.
194229
The pip build requirement (get_requires_for_build_*) states the floor, but
195230
conda-forge, pixi and --no-build-isolation installs bypass it, so the check
@@ -201,12 +236,8 @@ def _check_build_configuration(cuda_path: str, cuda_major: str) -> None:
201236
"""
202237
floor = _load_bindings_floor()
203238
major = int(cuda_major)
204-
if major not in floor.CUDA_BINDINGS_FLOOR:
205-
raise RuntimeError(
206-
f"cuda.core does not support CUDA {major}; supported CUDA major versions: "
207-
f"{', '.join(str(m) for m in floor.SUPPORTED_CUDA_MAJORS)}"
208-
)
209-
requirement = floor.pip_requirement(major)
239+
floor_triple = _floor_for(major)
240+
requirement = floor.bindings_requirement(floor_triple)
210241

211242
try:
212243
bindings_version = _import_cuda_bindings().__version__
@@ -226,9 +257,9 @@ def _check_build_configuration(cuda_path: str, cuda_major: str) -> None:
226257
f"Building cuda.core for CUDA {major}, but the installed cuda-bindings is "
227258
f"{bindings_version}. Install '{requirement}'."
228259
)
229-
if bindings < floor.CUDA_BINDINGS_FLOOR[major]:
260+
if bindings < floor_triple:
230261
raise RuntimeError(
231-
f"cuda.core requires cuda-bindings >= {floor.format_version(floor.CUDA_BINDINGS_FLOOR[major])} "
262+
f"cuda.core requires cuda-bindings >= {floor.format_version(floor_triple)} "
232263
f"for CUDA {major}, but {bindings_version} is installed. Install '{requirement}'."
233264
)
234265

@@ -242,16 +273,15 @@ def _check_build_configuration(cuda_path: str, cuda_major: str) -> None:
242273
"Point CUDA_PATH or CUDA_HOME at a matching CUDA Toolkit, or install matching cuda-bindings."
243274
)
244275
print(f"Build configuration: CUDA {header[0]}.{header[1]} headers, cuda-bindings {bindings_version}")
245-
_write_build_info(major, cuda_version, floor.CUDA_BINDINGS_FLOOR[major], bindings_version)
276+
_write_build_info(major, cuda_version, floor_triple, bindings_version)
246277

247278

248279
def _build_define_macros(cuda_major: str) -> list:
249280
"""Preprocessor macros that carry the build decision into the C++ (see _cpp/rt/versions.hpp)."""
250-
floor = _load_bindings_floor()
251281
major = int(cuda_major)
252282
return [
253283
("CUDA_CORE_BUILD_MAJOR", str(major)),
254-
("CUDA_CORE_MIN_CUDA_VERSION", str(floor.cuda_version_of(floor.CUDA_BINDINGS_FLOOR[major]))),
284+
("CUDA_CORE_MIN_CUDA_VERSION", str(_load_bindings_floor().cuda_version_of(_floor_for(major)))),
255285
]
256286

257287

@@ -602,14 +632,7 @@ def _get_cuda_bindings_require():
602632
Honored by isolated builds only; _check_build_configuration() enforces the
603633
same rule for every other build path.
604634
"""
605-
floor = _load_bindings_floor()
606-
cuda_major = int(_determine_cuda_major_version())
607-
if cuda_major not in floor.CUDA_BINDINGS_FLOOR:
608-
raise RuntimeError(
609-
f"cuda.core does not support CUDA {cuda_major}; supported CUDA major versions: "
610-
f"{', '.join(str(m) for m in floor.SUPPORTED_CUDA_MAJORS)}"
611-
)
612-
return [floor.pip_requirement(cuda_major)]
635+
return [_load_bindings_floor().bindings_requirement(_floor_for(_determine_cuda_major_version()))]
613636

614637

615638
def get_requires_for_build_editable(config_settings=None):

‎cuda_core/cuda/core/__init__.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,17 +41,17 @@ def load_build_module(name: str, cuda_major: int):
4141
try:
4242
cuda_major = int(version_str.split(".")[0])
4343
except ValueError:
44-
cuda_major = -1
45-
if cuda_major not in (12, 13):
46-
raise ImportError(f"cuda-bindings 12.x or 13.x must be installed (found {version_str})")
44+
raise ImportError(f"a cuda-bindings release must be installed (found version {version_str!r})") from None
4745
try:
4846
floor = load_build_module("_bindings_floor", cuda_major)
4947
info = load_build_module("_build_info", cuda_major)
5048
except ModuleNotFoundError as exc:
5149
raise ImportError(
5250
f"this cuda.core installation has no build for CUDA {cuda_major} (installed cuda-bindings: {version_str})"
5351
) from exc
54-
floor.check_installed_bindings(version_str, info.CUDA_MAJOR, info.CUDA_VERSION, __version__)
52+
floor.check_installed_bindings(
53+
version_str, info.CUDA_MAJOR, info.CUDA_VERSION, info.CUDA_BINDINGS_FLOOR, __version__
54+
)
5555

5656
subdir = f"cu{cuda_major}"
5757
try:

0 commit comments

Comments
 (0)