Use cuda.h for CTK guard-rails metadata.

Replace version.json-based CTK root metadata with cuda.h parsing so compatibility checks use a simpler, more universal toolkit source while preserving wheel-based metadata inference.

Made-with: Cursor

Author: rwgk

cuda_pathfinder/cuda/pathfinder/_compatibility_guard_rails.py

@@ -5,7 +5,6 @@
 
 import functools
 import importlib.metadata
-import json
 import os
 import re
 from collections.abc import Mapping
@@ -46,6 +45,7 @@
     QueryDriverCudaVersionError,
     query_driver_cuda_version,
 )
+from cuda.pathfinder._utils.toolkit_info import ReadCudaHeaderVersionError, read_cuda_header_version
 
 ItemKind: TypeAlias = str
 PackagedWith: TypeAlias = str
@@ -323,46 +323,62 @@ def _wheel_metadata_for_abs_path(abs_path: str) -> CtkMetadata | None:
     return CtkMetadata(ctk_version=ctk_version, ctk_root=None, source=source)
 
 
+def _normalized_ctk_root_for_cuda_header(cuda_header_path: Path) -> Path:
+    ctk_root = cuda_header_path.parent.parent
+    if ctk_root.parent.name == "targets":
+        return ctk_root.parent.parent
+    return ctk_root
+
+
 @functools.cache
-def _read_ctk_version(ctk_root: str) -> CtkVersion | None:
-    version_json_path = os.path.join(ctk_root, "version.json")
-    if not os.path.isfile(version_json_path):
-        return None
-    with open(version_json_path, encoding="utf-8") as fobj:
-        payload = json.load(fobj)
-    if not isinstance(payload, dict):
-        return None
-    cuda_entry = payload.get("cuda")
-    if not isinstance(cuda_entry, dict):
+def _cuda_header_metadata_for_ctk_root_candidate(ctk_root_candidate: str) -> CtkMetadata | None:
+    candidate_path = Path(ctk_root_candidate)
+    header_paths: list[Path] = []
+
+    direct_header = candidate_path / "include" / "cuda.h"
+    if direct_header.is_file():
+        header_paths.append(direct_header)
+
+    targets_dir = candidate_path / "targets"
+    if targets_dir.is_dir():
+        header_paths.extend(sorted(path for path in targets_dir.glob("*/include/cuda.h") if path.is_file()))
+
+    matches: list[tuple[CtkVersion, Path, Path]] = []
+    for cuda_header_path in header_paths:
+        try:
+            version = read_cuda_header_version(str(cuda_header_path))
+        except ReadCudaHeaderVersionError:
+            continue
+        matches.append(
+            (
+                CtkVersion(major=version.major, minor=version.minor),
+                _normalized_ctk_root_for_cuda_header(cuda_header_path),
+                cuda_header_path,
+            )
+        )
+
+    if not matches:
         return None
-    cuda_version = cuda_entry.get("version")
-    if not isinstance(cuda_version, str):
+
+    ctk_version, ctk_root, source_path = matches[0]
+    if any(other_version != ctk_version for other_version, _other_root, _other_source in matches[1:]):
         return None
-    return _parse_ctk_version(cuda_version)
+
+    return CtkMetadata(
+        ctk_version=ctk_version,
+        ctk_root=str(ctk_root),
+        source=f"cuda.h at {source_path}",
+    )
 
 
-def _find_enclosing_ctk_root(abs_path: str) -> str | None:
+def _ctk_metadata_for_abs_path(abs_path: str) -> CtkMetadata | None:
     current = Path(abs_path)
     if current.is_file():
         current = current.parent
     for candidate in (current, *current.parents):
-        ctk_root = str(candidate)
-        if _read_ctk_version(ctk_root) is not None:
-            return ctk_root
-    return None
-
-
-def _ctk_metadata_for_abs_path(abs_path: str) -> CtkMetadata | None:
-    ctk_root = _find_enclosing_ctk_root(abs_path)
-    if ctk_root is not None:
-        ctk_version = _read_ctk_version(ctk_root)
-        if ctk_version is not None:
-            version_json_path = os.path.join(ctk_root, "version.json")
-            return CtkMetadata(
-                ctk_version=ctk_version,
-                ctk_root=ctk_root,
-                source=f"version.json at {version_json_path}",
-            )
+        ctk_metadata = _cuda_header_metadata_for_ctk_root_candidate(str(candidate))
+        if ctk_metadata is not None:
+            return ctk_metadata
     return _wheel_metadata_for_abs_path(abs_path)
 
 
@@ -468,7 +484,7 @@ def compatibility_check(
                 status="insufficient_metadata",
                 message=(
                     "v1 compatibility checks require either an enclosing CUDA Toolkit root "
-                    "with version.json or wheel metadata that can be traced to an installed "
+                    "with cuda.h or wheel metadata that can be traced to an installed "
                     f"cuda-toolkit distribution. Could not determine the CTK version for {item.describe()}."
                 ),
             )
@@ -545,7 +561,7 @@ def _enforce_ctk_metadata(self, item: ResolvedItem) -> None:
             return
         raise CompatibilityInsufficientMetadataError(
             "v1 compatibility checks require either an enclosing CUDA Toolkit root "
-            "with version.json or wheel metadata that can be traced to an installed "
+            "with cuda.h or wheel metadata that can be traced to an installed "
             f"cuda-toolkit distribution. Could not determine the CTK version for {item.describe()}."
         )
 

cuda_pathfinder/tests/test_compatibility_guard_rails.py

@@ -2,7 +2,6 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import importlib
-import json
 import os
 from pathlib import Path
 
@@ -36,10 +35,22 @@ def _default_process_wide_guard_rails_mode(monkeypatch):
     monkeypatch.delenv(COMPATIBILITY_GUARD_RAILS_ENV_VAR, raising=False)
 
 
-def _write_version_json(ctk_root: Path, toolkit_version: str) -> None:
-    ctk_root.mkdir(parents=True, exist_ok=True)
-    payload = {"cuda": {"version": toolkit_version}}
-    (ctk_root / "version.json").write_text(json.dumps(payload), encoding="utf-8")
+def _write_cuda_h(
+    ctk_root: Path,
+    toolkit_version: str,
+    *,
+    include_dir_parts: tuple[str, ...] = ("targets", "x86_64-linux", "include"),
+) -> None:
+    parts = toolkit_version.split(".")
+    if len(parts) < 2:
+        raise AssertionError(f"Expected at least major.minor in toolkit version, got {toolkit_version!r}")
+    encoded = int(parts[0]) * 1000 + int(parts[1]) * 10
+    cuda_h_path = ctk_root.joinpath(*include_dir_parts, "cuda.h")
+    cuda_h_path.parent.mkdir(parents=True, exist_ok=True)
+    cuda_h_path.write_text(
+        f"#ifndef CUDA_H\n#define CUDA_H\n#define CUDA_VERSION {encoded}\n#endif\n",
+        encoding="utf-8",
+    )
 
 
 def _touch(path: Path) -> str:
@@ -76,11 +87,7 @@ def _located_bitcode_lib(name: str, abs_path: str) -> LocatedBitcodeLib:
 
 
 def _driver_cuda_version(encoded: int) -> DriverCudaVersion:
-    return DriverCudaVersion(
-        encoded=encoded,
-        major=encoded // 1000,
-        minor=(encoded % 1000) // 10,
-    )
+    return DriverCudaVersion.from_encoded(encoded)
 
 
 class _FakeDistribution:
@@ -111,8 +118,9 @@ def _assert_real_ctk_backed_path(path: str) -> None:
     if current.is_file():
         current = current.parent
     for candidate in (current, *current.parents):
-        version_json_path = candidate / "version.json"
-        if version_json_path.is_file():
+        if (candidate / "include" / "cuda.h").is_file():
+            return
+        if any(path.is_file() for path in (candidate / "targets").glob("*/include/cuda.h")):
             return
     for env_var in ("CUDA_PATH", "CUDA_HOME"):
         ctk_root = os.environ.get(env_var)
@@ -122,7 +130,7 @@ def _assert_real_ctk_backed_path(path: str) -> None:
         if os.path.commonpath((norm_path, norm_ctk_root)) == norm_ctk_root:
             return
     raise AssertionError(
-        "Expected a site-packages path, a path under a CTK root with version.json, "
+        "Expected a site-packages path, a path under a CTK root with cuda.h, "
         f"or a path under CUDA_PATH/CUDA_HOME, got {path!r}"
     )
 
@@ -220,7 +228,7 @@ def fail_raw_fallback(_libname: str) -> LoadedDL:
 
 @pytest.mark.parametrize("env_value", [None, ""])
 def test_public_apis_default_to_strict_when_env_var_is_unset_or_empty(monkeypatch, tmp_path, env_value):
-    lib_path = _touch(tmp_path / "no-version-json" / "targets" / "x86_64-linux" / "lib" / "libnvrtc.so.12")
+    lib_path = _touch(tmp_path / "no-cuda-h" / "targets" / "x86_64-linux" / "lib" / "libnvrtc.so.12")
 
     monkeypatch.setattr(compatibility_module, "_load_nvidia_dynamic_lib", lambda _libname: _loaded_dl(lib_path))
     monkeypatch.setattr(
@@ -238,12 +246,12 @@ def fail_raw_fallback(_libname: str) -> LoadedDL:
     else:
         monkeypatch.setenv(COMPATIBILITY_GUARD_RAILS_ENV_VAR, env_value)
 
-    with pytest.raises(CompatibilityInsufficientMetadataError, match="version.json"):
+    with pytest.raises(CompatibilityInsufficientMetadataError, match="cuda.h"):
         pathfinder.load_nvidia_dynamic_lib("nvrtc")
 
 
 def test_public_apis_best_effort_fall_back_on_insufficient_metadata(monkeypatch, tmp_path):
-    guarded_lib_path = _touch(tmp_path / "no-version-json" / "targets" / "x86_64-linux" / "lib" / "libnvrtc.so.12")
+    guarded_lib_path = _touch(tmp_path / "no-cuda-h" / "targets" / "x86_64-linux" / "lib" / "libnvrtc.so.12")
     raw_loaded = _loaded_dl("/opt/mock/libnvrtc.so.12", found_via="system-search")
 
     monkeypatch.setenv(COMPATIBILITY_GUARD_RAILS_ENV_VAR, "best_effort")
@@ -292,8 +300,8 @@ def test_public_apis_reject_invalid_guard_rails_mode(monkeypatch):
 def test_public_apis_share_process_wide_guard_rails_state(monkeypatch, tmp_path):
     lib_root = tmp_path / "cuda-12.8"
     hdr_root = tmp_path / "cuda-12.9"
-    _write_version_json(lib_root, "12.8.20250303")
-    _write_version_json(hdr_root, "12.9.20250531")
+    _write_cuda_h(lib_root, "12.8.20250303")
+    _write_cuda_h(hdr_root, "12.9.20250531")
 
     lib_path = _touch(lib_root / "targets" / "x86_64-linux" / "lib" / "libnvrtc.so.12")
     hdr_dir = hdr_root / "targets" / "x86_64-linux" / "include"
@@ -320,7 +328,7 @@ def test_public_apis_share_process_wide_guard_rails_state(monkeypatch, tmp_path)
 
 def test_load_dynamic_lib_then_find_headers_same_ctk_version(monkeypatch, tmp_path):
     ctk_root = tmp_path / "cuda-12.9"
-    _write_version_json(ctk_root, "12.9.20250531")
+    _write_cuda_h(ctk_root, "12.9.20250531")
     lib_path = _touch(ctk_root / "targets" / "x86_64-linux" / "lib" / "libnvrtc.so.12")
     hdr_dir = ctk_root / "targets" / "x86_64-linux" / "include"
     _touch(hdr_dir / "nvrtc.h")
@@ -344,8 +352,8 @@ def test_load_dynamic_lib_then_find_headers_same_ctk_version(monkeypatch, tmp_pa
 def test_exact_ctk_major_minor_match_is_required(monkeypatch, tmp_path):
     lib_root = tmp_path / "cuda-12.8"
     hdr_root = tmp_path / "cuda-12.9"
-    _write_version_json(lib_root, "12.8.20250303")
-    _write_version_json(hdr_root, "12.9.20250531")
+    _write_cuda_h(lib_root, "12.8.20250303")
+    _write_cuda_h(hdr_root, "12.9.20250531")
 
     lib_path = _touch(lib_root / "targets" / "x86_64-linux" / "lib" / "libnvrtc.so.12")
     hdr_dir = hdr_root / "targets" / "x86_64-linux" / "include"
@@ -367,7 +375,7 @@ def test_exact_ctk_major_minor_match_is_required(monkeypatch, tmp_path):
 
 def test_driver_major_must_not_be_older_than_ctk_major(monkeypatch, tmp_path):
     ctk_root = tmp_path / "cuda-13.0"
-    _write_version_json(ctk_root, "13.0.20251003")
+    _write_cuda_h(ctk_root, "13.0.20251003")
     lib_path = _touch(ctk_root / "targets" / "x86_64-linux" / "lib" / "libnvrtc.so.13")
 
     monkeypatch.setattr(compatibility_module, "_load_nvidia_dynamic_lib", lambda _libname: _loaded_dl(lib_path))
@@ -378,17 +386,31 @@ def test_driver_major_must_not_be_older_than_ctk_major(monkeypatch, tmp_path):
         guard_rails.load_nvidia_dynamic_lib("nvrtc")
 
 
-def test_missing_version_json_raises_insufficient_metadata(monkeypatch, tmp_path):
-    lib_path = _touch(tmp_path / "no-version-json" / "targets" / "x86_64-linux" / "lib" / "libnvrtc.so.12")
+def test_missing_cuda_h_raises_insufficient_metadata(monkeypatch, tmp_path):
+    lib_path = _touch(tmp_path / "no-cuda-h" / "targets" / "x86_64-linux" / "lib" / "libnvrtc.so.12")
 
     monkeypatch.setattr(compatibility_module, "_load_nvidia_dynamic_lib", lambda _libname: _loaded_dl(lib_path))
 
     guard_rails = CompatibilityGuardRails(driver_cuda_version=_driver_cuda_version(13000))
 
-    with pytest.raises(CompatibilityInsufficientMetadataError, match="version.json"):
+    with pytest.raises(CompatibilityInsufficientMetadataError, match="cuda.h"):
         guard_rails.load_nvidia_dynamic_lib("nvrtc")
 
 
+def test_windows_style_ctk_root_uses_root_include_cuda_h(monkeypatch, tmp_path):
+    ctk_root = tmp_path / "cuda-13.2"
+    _write_cuda_h(ctk_root, "13.2.20251003", include_dir_parts=("include",))
+    lib_path = _touch(ctk_root / "bin" / "x64" / "nvrtc64_130_0.dll")
+
+    monkeypatch.setattr(compatibility_module, "_load_nvidia_dynamic_lib", lambda _libname: _loaded_dl(lib_path))
+
+    guard_rails = CompatibilityGuardRails(driver_cuda_version=_driver_cuda_version(13000))
+
+    loaded = guard_rails.load_nvidia_dynamic_lib("nvrtc")
+
+    assert loaded.abs_path == lib_path
+
+
 def test_other_packaging_raises_insufficient_metadata(monkeypatch, tmp_path):
     abs_path = _touch(tmp_path / "site-packages" / "nvidia" / "nvshmem" / "lib" / "libnvshmem_device.bc")
 
@@ -407,7 +429,7 @@ def test_other_packaging_raises_insufficient_metadata(monkeypatch, tmp_path):
 def test_driver_libs_do_not_lock_ctk_anchor(monkeypatch, tmp_path):
     driver_lib_path = _touch(tmp_path / "driver-root" / "libnvidia-ml.so.1")
     ctk_root = tmp_path / "cuda-12.9"
-    _write_version_json(ctk_root, "12.9.20250531")
+    _write_cuda_h(ctk_root, "12.9.20250531")
     ctk_lib_path = _touch(ctk_root / "targets" / "x86_64-linux" / "lib" / "libnvrtc.so.12")
 
     def fake_load_nvidia_dynamic_lib(libname: str) -> LoadedDL:
@@ -432,8 +454,8 @@ def test_driver_libs_do_not_mask_later_ctk_mismatch(monkeypatch, tmp_path):
     driver_lib_path = _touch(tmp_path / "driver-root" / "libnvidia-ml.so.1")
     lib_root = tmp_path / "cuda-12.8"
     hdr_root = tmp_path / "cuda-12.9"
-    _write_version_json(lib_root, "12.8.20250303")
-    _write_version_json(hdr_root, "12.9.20250531")
+    _write_cuda_h(lib_root, "12.8.20250303")
+    _write_cuda_h(hdr_root, "12.9.20250531")
 
     lib_path = _touch(lib_root / "targets" / "x86_64-linux" / "lib" / "libnvrtc.so.12")
     hdr_dir = hdr_root / "targets" / "x86_64-linux" / "include"
@@ -506,7 +528,7 @@ def test_wheel_metadata_accepts_exact_and_range_requirements(monkeypatch, tmp_pa
 
 def test_constraints_accept_string_and_tuple_forms(monkeypatch, tmp_path):
     ctk_root = tmp_path / "cuda-12.9"
-    _write_version_json(ctk_root, "12.9.20250531")
+    _write_cuda_h(ctk_root, "12.9.20250531")
     lib_path = _touch(ctk_root / "targets" / "x86_64-linux" / "lib" / "libnvrtc.so.12")
 
     monkeypatch.setattr(compatibility_module, "_load_nvidia_dynamic_lib", lambda _libname: _loaded_dl(lib_path))
@@ -524,7 +546,7 @@ def test_constraints_accept_string_and_tuple_forms(monkeypatch, tmp_path):
 
 def test_constraint_failure_raises(monkeypatch, tmp_path):
     ctk_root = tmp_path / "cuda-12.9"
-    _write_version_json(ctk_root, "12.9.20250531")
+    _write_cuda_h(ctk_root, "12.9.20250531")
     lib_path = _touch(ctk_root / "targets" / "x86_64-linux" / "lib" / "libnvrtc.so.12")
 
     monkeypatch.setattr(compatibility_module, "_load_nvidia_dynamic_lib", lambda _libname: _loaded_dl(lib_path))
@@ -541,7 +563,7 @@ def test_constraint_failure_raises(monkeypatch, tmp_path):
 
 def test_static_bitcode_and_binary_methods_participate_in_checks(monkeypatch, tmp_path):
     ctk_root = tmp_path / "cuda-12.9"
-    _write_version_json(ctk_root, "12.9.20250531")
+    _write_cuda_h(ctk_root, "12.9.20250531")
 
     lib_path = _touch(ctk_root / "targets" / "x86_64-linux" / "lib" / "libnvrtc.so.12")
     static_path = _touch(ctk_root / "targets" / "x86_64-linux" / "lib" / "libcudadevrt.a")
@@ -575,7 +597,7 @@ def test_static_bitcode_and_binary_methods_participate_in_checks(monkeypatch, tm
 
 def test_guard_rails_query_driver_cuda_version_by_default(monkeypatch, tmp_path):
     ctk_root = tmp_path / "cuda-12.9"
-    _write_version_json(ctk_root, "12.9.20250531")
+    _write_cuda_h(ctk_root, "12.9.20250531")
     lib_path = _touch(ctk_root / "targets" / "x86_64-linux" / "lib" / "libnvrtc.so.12")
 
     query_calls: list[int] = []
@@ -598,7 +620,7 @@ def fake_query_driver_cuda_version() -> DriverCudaVersion:
 
 def test_guard_rails_wrap_driver_query_failures(monkeypatch, tmp_path):
     ctk_root = tmp_path / "cuda-12.9"
-    _write_version_json(ctk_root, "12.9.20250531")
+    _write_cuda_h(ctk_root, "12.9.20250531")
     lib_path = _touch(ctk_root / "targets" / "x86_64-linux" / "lib" / "libnvrtc.so.12")
 
     monkeypatch.setattr(compatibility_module, "_load_nvidia_dynamic_lib", lambda _libname: _loaded_dl(lib_path))