feat(pathfinder): support finding static libraries like libcudadevrt.a (#1690)

* feat(pathfinder): support finding static libraries like libcudadevrt.a (#716)

Add locate_static_lib() and find_static_lib() APIs to cuda.pathfinder
for discovering native static libraries (e.g. libcudadevrt.a on Linux,
cudadevrt.lib on Windows). Searches site-packages, conda, and
CUDA_HOME/CUDA_PATH in that order, matching the existing bitcode lib
pattern. Update cuda_core's device launch test to use the new API.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: skip device launch test when cudadevrt linking fails

The pathfinder now finds libcudadevrt.a via site-packages even without
CUDA_HOME, but the found library may be version-incompatible with the
local toolkit. Catch linker errors and skip gracefully.

Co-authored-by: Cursor <cursoragent@cursor.com>

* revert: drop test_device_launch.py changes

The pathfinder finds libcudadevrt.a via site-packages, which may be
version-incompatible with the local CTK the test compiles against.
Leave the test helper as-is for now; migrating it to pathfinder
requires version-aware discovery.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat: use find_static_lib in device launch test

Replace the manual _find_cudadevrt_library() helper with
cuda.pathfinder.find_static_lib("cudadevrt").

Co-authored-by: Cursor <cursoragent@cursor.com>

* ci: constrain cuda-toolkit to match local CTK version

When LOCAL_CTK=1, the pip dependency group test-cu13 pulls in
cuda-toolkit[cudart]==13.* which resolves to the latest 13.x pip
wheel. This can install nvidia-cuda-runtime from a newer minor
version than the local CTK, causing version mismatches (e.g.,
nvjitlink 13.0 rejecting a 13.1 libcudadevrt.a).

Constrain cuda-toolkit to CUDA_VER's major.minor so pip installs
a version consistent with the local CTK.

Closes #1691

Co-authored-by: Cursor <cursoragent@cursor.com>

* refactor: use importorskip and f-string for pathfinder in device launch test

Made-with: Cursor

* refactor: use quote_for_shell in test_find_static_lib info_summary_append

Made-with: Cursor

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: cpcloud

ci/tools/run-tests

@@ -73,10 +73,13 @@ elif [[ "${test_module}" == "core" ]]; then
   fi
 
   pushd ./cuda_core
+  CUDA_VER_MINOR="$(cut -d '.' -f 1-2 <<< "${CUDA_VER}")"
   if [[ "${LOCAL_CTK}" == 1 ]]; then
     # We already installed cuda-bindings, and all CTK components exist locally,
     # so just install the test dependencies.
-    pip install "${CUDA_CORE_ARTIFACTS_DIR}"/*.whl --group "test-cu${TEST_CUDA_MAJOR}${FREE_THREADING}"
+    # Constrain cuda-toolkit to match the local CTK version to avoid
+    # pip pulling in a newer nvidia-cuda-runtime that conflicts with it.
+    pip install "${CUDA_CORE_ARTIFACTS_DIR}"/*.whl --group "test-cu${TEST_CUDA_MAJOR}${FREE_THREADING}" "cuda-toolkit==${CUDA_VER_MINOR}.*"
   else
     pip install $(ls "${CUDA_CORE_ARTIFACTS_DIR}"/*.whl)["cu${TEST_CUDA_MAJOR}"] --group "test-cu${TEST_CUDA_MAJOR}${FREE_THREADING}"
   fi

cuda_core/tests/graph/test_device_launch.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: LicenseRef-NVIDIA-SOFTWARE-LICENSE
 
 """Device-side graph launch tests.
@@ -10,9 +10,6 @@
 - The kernel calling cudaGraphLaunch() must itself be launched from within a graph
 """
 
-import os
-import sys
-
 import numpy as np
 import pytest
 from cuda.core import (
@@ -29,30 +26,6 @@
 )
 
 
-def _find_cudadevrt_library():
-    """Find the CUDA device runtime static library using CUDA_HOME.
-
-    See https://github.com/NVIDIA/cuda-python/issues/716 for future improvements
-    to make this discovery more robust via cuda.pathfinder.
-
-    Returns:
-        Path to libcudadevrt.a (Linux) or cudadevrt.lib (Windows), or None if not found.
-    """
-    cuda_home = os.environ.get("CUDA_HOME") or os.environ.get("CUDA_PATH")
-    if not cuda_home:
-        return None
-
-    if sys.platform == "win32":
-        path = os.path.join(cuda_home, "lib", "x64", "cudadevrt.lib")
-    else:
-        # Try lib64 first (common on Linux), fall back to lib
-        path = os.path.join(cuda_home, "lib64", "libcudadevrt.a")
-        if not os.path.isfile(path):
-            path = os.path.join(cuda_home, "lib", "libcudadevrt.a")
-
-    return path if os.path.isfile(path) else None
-
-
 def _get_device_arch():
     """Get the current device's architecture string."""
     return "".join(f"{i}" for i in Device().compute_capability)
@@ -80,9 +53,11 @@ def _compile_device_launcher_kernel():
 
     Raises pytest.skip if libcudadevrt.a cannot be found.
     """
-    cudadevrt_path = _find_cudadevrt_library()
-    if cudadevrt_path is None:
-        pytest.skip("cudadevrt library not found (set CUDA_HOME or CUDA_PATH)")
+    pathfinder = pytest.importorskip("cuda.pathfinder")
+    try:
+        cudadevrt_path = pathfinder.find_static_lib("cudadevrt")
+    except pathfinder.StaticLibNotFoundError as e:
+        pytest.skip(f"cudadevrt library not found: {e}")
 
     code = """
     extern "C" __global__ void launch_graph_from_device(cudaGraphExec_t graph) {

cuda_pathfinder/cuda/pathfinder/__init__.py

@@ -40,6 +40,21 @@
 from cuda.pathfinder._static_libs.find_bitcode_lib import (
     locate_bitcode_lib as locate_bitcode_lib,
 )
+from cuda.pathfinder._static_libs.find_static_lib import (
+    SUPPORTED_STATIC_LIBS as _SUPPORTED_STATIC_LIBS,
+)
+from cuda.pathfinder._static_libs.find_static_lib import (
+    LocatedStaticLib as LocatedStaticLib,
+)
+from cuda.pathfinder._static_libs.find_static_lib import (
+    StaticLibNotFoundError as StaticLibNotFoundError,
+)
+from cuda.pathfinder._static_libs.find_static_lib import (
+    find_static_lib as find_static_lib,
+)
+from cuda.pathfinder._static_libs.find_static_lib import (
+    locate_static_lib as locate_static_lib,
+)
 
 from cuda.pathfinder._version import __version__  # isort: skip  # noqa: F401
 
@@ -61,6 +76,11 @@
 #: Example value: ``"device"``.
 SUPPORTED_BITCODE_LIBS = _SUPPORTED_BITCODE_LIBS
 
+#: Tuple of supported static library names that can be resolved
+#: via ``locate_static_lib()`` and ``find_static_lib()``.
+#: Example value: ``"cudadevrt"``.
+SUPPORTED_STATIC_LIBS = _SUPPORTED_STATIC_LIBS
+
 # Backward compatibility: _find_nvidia_header_directory was added in release 1.2.2.
 # It will be removed in release 1.2.4.
 _find_nvidia_header_directory = find_nvidia_header_directory

cuda_pathfinder/cuda/pathfinder/_static_libs/find_static_lib.py

@@ -0,0 +1,166 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import functools
+import os
+from dataclasses import dataclass
+from typing import NoReturn, TypedDict
+
+from cuda.pathfinder._utils.env_vars import get_cuda_home_or_path
+from cuda.pathfinder._utils.find_sub_dirs import find_sub_dirs_all_sitepackages
+from cuda.pathfinder._utils.platform_aware import IS_WINDOWS
+
+
+class StaticLibNotFoundError(RuntimeError):
+    """Raised when a static library cannot be found."""
+
+
+@dataclass(frozen=True)
+class LocatedStaticLib:
+    """Information about a located static library."""
+
+    name: str
+    abs_path: str
+    filename: str
+    found_via: str
+
+
+class _StaticLibInfo(TypedDict):
+    filename: str
+    ctk_rel_paths: tuple[str, ...]
+    conda_rel_path: str
+    site_packages_dirs: tuple[str, ...]
+
+
+_SUPPORTED_STATIC_LIBS_INFO: dict[str, _StaticLibInfo] = {
+    "cudadevrt": {
+        "filename": "cudadevrt.lib" if IS_WINDOWS else "libcudadevrt.a",
+        "ctk_rel_paths": (os.path.join("lib", "x64"),) if IS_WINDOWS else ("lib64", "lib"),
+        "conda_rel_path": os.path.join("lib", "x64") if IS_WINDOWS else "lib",
+        "site_packages_dirs": (
+            ("nvidia/cu13/lib/x64", "nvidia/cuda_runtime/lib/x64")
+            if IS_WINDOWS
+            else ("nvidia/cu13/lib", "nvidia/cuda_runtime/lib")
+        ),
+    },
+}
+
+SUPPORTED_STATIC_LIBS: tuple[str, ...] = tuple(sorted(_SUPPORTED_STATIC_LIBS_INFO.keys()))
+
+
+def _no_such_file_in_dir(dir_path: str, filename: str, error_messages: list[str], attachments: list[str]) -> None:
+    error_messages.append(f"No such file: {os.path.join(dir_path, filename)}")
+    if os.path.isdir(dir_path):
+        attachments.append(f'  listdir("{dir_path}"):')
+        for node in sorted(os.listdir(dir_path)):
+            attachments.append(f"    {node}")
+    else:
+        attachments.append(f'  Directory does not exist: "{dir_path}"')
+
+
+class _FindStaticLib:
+    def __init__(self, name: str) -> None:
+        if name not in _SUPPORTED_STATIC_LIBS_INFO:
+            raise ValueError(f"Unknown static library: '{name}'. Supported: {', '.join(SUPPORTED_STATIC_LIBS)}")
+        self.name: str = name
+        self.config: _StaticLibInfo = _SUPPORTED_STATIC_LIBS_INFO[name]
+        self.filename: str = self.config["filename"]
+        self.ctk_rel_paths: tuple[str, ...] = self.config["ctk_rel_paths"]
+        self.conda_rel_path: str = self.config["conda_rel_path"]
+        self.site_packages_dirs: tuple[str, ...] = self.config["site_packages_dirs"]
+        self.error_messages: list[str] = []
+        self.attachments: list[str] = []
+
+    def try_site_packages(self) -> str | None:
+        for rel_dir in self.site_packages_dirs:
+            sub_dir = tuple(rel_dir.split("/"))
+            for abs_dir in find_sub_dirs_all_sitepackages(sub_dir):
+                file_path = os.path.join(abs_dir, self.filename)
+                if os.path.isfile(file_path):
+                    return file_path
+        return None
+
+    def try_with_conda_prefix(self) -> str | None:
+        conda_prefix = os.environ.get("CONDA_PREFIX")
+        if not conda_prefix:
+            return None
+
+        anchor = os.path.join(conda_prefix, "Library") if IS_WINDOWS else conda_prefix
+        file_path = os.path.join(anchor, self.conda_rel_path, self.filename)
+        if os.path.isfile(file_path):
+            return file_path
+        return None
+
+    def try_with_cuda_home(self) -> str | None:
+        cuda_home = get_cuda_home_or_path()
+        if cuda_home is None:
+            self.error_messages.append("CUDA_HOME/CUDA_PATH not set")
+            return None
+
+        for rel_path in self.ctk_rel_paths:
+            file_path = os.path.join(cuda_home, rel_path, self.filename)
+            if os.path.isfile(file_path):
+                return file_path
+
+        _no_such_file_in_dir(
+            os.path.join(cuda_home, self.ctk_rel_paths[0]),
+            self.filename,
+            self.error_messages,
+            self.attachments,
+        )
+        return None
+
+    def raise_not_found_error(self) -> NoReturn:
+        err = ", ".join(self.error_messages) if self.error_messages else "No search paths available"
+        att = "\n".join(self.attachments) if self.attachments else ""
+        raise StaticLibNotFoundError(f'Failure finding "{self.filename}": {err}\n{att}')
+
+
+def locate_static_lib(name: str) -> LocatedStaticLib:
+    """Locate a static library by name.
+
+    Raises:
+        ValueError: If ``name`` is not a supported static library.
+        StaticLibNotFoundError: If the static library cannot be found.
+    """
+    finder = _FindStaticLib(name)
+
+    abs_path = finder.try_site_packages()
+    if abs_path is not None:
+        return LocatedStaticLib(
+            name=name,
+            abs_path=abs_path,
+            filename=finder.filename,
+            found_via="site-packages",
+        )
+
+    abs_path = finder.try_with_conda_prefix()
+    if abs_path is not None:
+        return LocatedStaticLib(
+            name=name,
+            abs_path=abs_path,
+            filename=finder.filename,
+            found_via="conda",
+        )
+
+    abs_path = finder.try_with_cuda_home()
+    if abs_path is not None:
+        return LocatedStaticLib(
+            name=name,
+            abs_path=abs_path,
+            filename=finder.filename,
+            found_via="CUDA_HOME",
+        )
+
+    finder.raise_not_found_error()
+
+
+@functools.cache
+def find_static_lib(name: str) -> str:
+    """Find the absolute path to a static library.
+
+    Raises:
+        ValueError: If ``name`` is not a supported static library.
+        StaticLibNotFoundError: If the static library cannot be found.
+    """
+    return locate_static_lib(name).abs_path