pathfinder: add locate_nvidia_dynamic_lib and find_nvidia_dynamic_lib

cuda_pathfinder/cuda/pathfinder/__init__.py

@@ -11,6 +11,11 @@
     find_nvidia_binary_utility as find_nvidia_binary_utility,
 )
 from cuda.pathfinder._binaries.supported_nvidia_binaries import SUPPORTED_BINARIES as _SUPPORTED_BINARIES
+from cuda.pathfinder._dynamic_libs.find_nvidia_dynamic_lib import LocatedDynamicLib as LocatedDynamicLib
+from cuda.pathfinder._dynamic_libs.find_nvidia_dynamic_lib import find_nvidia_dynamic_lib as find_nvidia_dynamic_lib
+from cuda.pathfinder._dynamic_libs.find_nvidia_dynamic_lib import (
+    locate_nvidia_dynamic_lib as locate_nvidia_dynamic_lib,
+)
 from cuda.pathfinder._dynamic_libs.load_dl_common import (
     DynamicLibNotAvailableError as DynamicLibNotAvailableError,
 )
@@ -76,8 +81,8 @@
 SUPPORTED_BINARY_UTILITIES = _SUPPORTED_BINARIES
 
 #: Tuple of CUDA Toolkit dynamic library names supported by
-#: :func:`load_nvidia_dynamic_lib` for the current operating system and
-#: interpreter architecture.
+#: :func:`load_nvidia_dynamic_lib` and :func:`locate_nvidia_dynamic_lib` for
+#: the current operating system and interpreter architecture.
 SUPPORTED_NVIDIA_LIBNAMES = _SUPPORTED_NVIDIA_LIBNAMES
 
 #: Tuple of supported bitcode library names that can be resolved

cuda_pathfinder/cuda/pathfinder/_dynamic_libs/find_nvidia_dynamic_lib.py

@@ -0,0 +1,155 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import functools
+import os
+from dataclasses import dataclass
+
+from cuda.pathfinder._dynamic_libs.lib_descriptor import LIB_DESCRIPTORS
+from cuda.pathfinder._dynamic_libs.load_nvidia_dynamic_lib import (
+    _DRIVER_ONLY_LIBNAMES,
+    _resolve_system_loaded_abs_path_in_subprocess,
+    _try_ctk_root_canary,
+    check_libname,
+    raise_driver_lib_not_found,
+)
+from cuda.pathfinder._dynamic_libs.search_steps import (
+    EARLY_FIND_STEPS,
+    LATE_FIND_STEPS,
+    FindResult,
+    SearchContext,
+    run_find_steps,
+)
+
+
+@dataclass(frozen=True)
+class LocatedDynamicLib:
+    """Information about a located dynamic library."""
+
+    name: str
+    abs_path: str
+    filename: str
+    found_via: str
+
+
+def _find_with_system_search(libname: str) -> FindResult | None:
+    # The native loader search can only be observed by loading, so it runs in
+    # a fresh subprocess and the caller's process stays untouched.
+    abs_path = _resolve_system_loaded_abs_path_in_subprocess(libname)
+    if abs_path is None:
+        return None
+    return FindResult(abs_path, "system-search")
+
+
+def _locate_lib(libname: str) -> FindResult:
+    desc = LIB_DESCRIPTORS[libname]
+
+    if libname in _DRIVER_ONLY_LIBNAMES:
+        find = _find_with_system_search(libname)
+        if find is None:
+            raise_driver_lib_not_found(desc)
+        return find
+
+    ctx = SearchContext(desc)
+    find = run_find_steps(ctx, EARLY_FIND_STEPS)
+
+    # load_nvidia_dynamic_lib loads the required dependencies at this point and
+    # fails if one of them cannot be found.
+    for dep in desc.dependencies:
+        locate_nvidia_dynamic_lib(dep)
+
+    if find is not None:
+        return find
+
+    find = _find_with_system_search(libname)
+    if find is not None:
+        return find
+
+    find = run_find_steps(ctx, LATE_FIND_STEPS)
+    if find is not None:
+        return find
+
+    if desc.ctk_root_canary_anchor_libnames:
+        canary_abs_path = _try_ctk_root_canary(ctx)
+        if canary_abs_path is not None:
+            return FindResult(canary_abs_path, "system-ctk-root")
+
+    ctx.raise_not_found()
+
+
+def locate_nvidia_dynamic_lib(libname: str) -> LocatedDynamicLib:
+    """Locate an NVIDIA dynamic library by name without loading it.
+
+    Returns the file that :func:`load_nvidia_dynamic_lib` would load in a fresh
+    process. Use it where a path is needed but the library must not be loaded
+    into the current process, for example to pass a library to a build system.
+
+    Like :func:`load_nvidia_dynamic_lib`, it fails if a library that ``libname``
+    requires cannot be found. Optional dependencies are not checked.
+
+    Args:
+        libname (str): The short name of the library to locate (e.g.,
+            ``"cudart"``, ``"nvvm"``, etc.).
+
+    Returns:
+        LocatedDynamicLib: The absolute path of the library file and how it
+        was found.
+
+    Raises:
+        DynamicLibUnknownError: If ``libname`` is not a recognized library name.
+        DynamicLibNotAvailableError: If ``libname`` is recognized but not
+            supported on this platform.
+        DynamicLibNotFoundError: If the library cannot be found.
+
+    Search order:
+        The steps of :func:`load_nvidia_dynamic_lib`, in the same order, except
+        that a library already loaded in the current process is not taken into
+        account:
+
+        1. NVIDIA Python wheels (``site-packages``)
+        2. Conda environment (``CONDA_PREFIX``)
+        3. OS default mechanisms (``dlopen()`` / ``LoadLibraryExW()``), run in
+           a fresh Python subprocess
+        4. Environment variables (library-specific roots, then ``CUDA_PATH`` /
+           ``CUDA_HOME``)
+        5. Windows Program Files (configured libraries only)
+        6. CTK root canary probe (discoverable libs only)
+
+        Driver libraries (``"cuda"``, ``"nvml"``) use step 3 only.
+
+    Notes:
+        The result can differ from what :func:`load_nvidia_dynamic_lib` returns
+        in the current process when another component has already loaded the
+        library, or influences the native loader search (for example through
+        its ``RPATH``). A file that is found but fails to load is still
+        returned, since nothing is loaded.
+
+        The result of the native loader search (step 3) is cached for the life
+        of the process and shared with the CTK root canary probe, because each
+        search starts a Python subprocess.
+    """
+    check_libname(libname)
+    find = _locate_lib(libname)
+    return LocatedDynamicLib(
+        name=libname,
+        abs_path=find.abs_path,
+        filename=os.path.basename(find.abs_path),
+        found_via=find.found_via,
+    )
+
+
+@functools.cache
+def find_nvidia_dynamic_lib(libname: str) -> str:
+    """Find the absolute path of an NVIDIA dynamic library without loading it.
+
+    See :func:`locate_nvidia_dynamic_lib` for the search order.
+
+    Raises:
+        DynamicLibUnknownError: If ``libname`` is not a recognized library name.
+        DynamicLibNotAvailableError: If ``libname`` is recognized but not
+            supported on this platform.
+        DynamicLibNotFoundError: If the library cannot be found.
+    """
+    return locate_nvidia_dynamic_lib(libname).abs_path

cuda_pathfinder/cuda/pathfinder/_dynamic_libs/load_nvidia_dynamic_lib.py

@@ -7,7 +7,7 @@
 import struct
 import subprocess
 import sys
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, NoReturn
 
 from cuda.pathfinder._dynamic_libs.lib_descriptor import LIB_DESCRIPTORS
 from cuda.pathfinder._dynamic_libs.load_dl_common import (
@@ -66,12 +66,27 @@ def _load_driver_lib_no_cache(desc: LibDescriptor) -> LoadedDL:
     loaded = LOADER.load_with_system_search(desc)
     if loaded is not None:
         return loaded
+    raise_driver_lib_not_found(desc)
+
+
+def raise_driver_lib_not_found(desc: LibDescriptor) -> NoReturn:
     raise DynamicLibNotFoundError(
         f'"{desc.name}" is an NVIDIA driver library and can only be found via'
         f" system search. Ensure the NVIDIA display driver is installed."
     )
 
 
+def check_libname(libname: str) -> None:
+    """Raise if ``libname`` is unknown or not available on this platform."""
+    if libname not in _ALL_KNOWN_LIBNAMES:
+        raise DynamicLibUnknownError(f"Unknown library name: {libname!r}. Known names: {sorted(_ALL_KNOWN_LIBNAMES)}")
+    if libname not in ALL_AVAILABLE_LIBNAMES:
+        raise DynamicLibNotAvailableError(
+            f"Library name {libname!r} is known but not available on {_PLATFORM_NAME}. "
+            f"Supported names on {_PLATFORM_NAME}: {sorted(ALL_AVAILABLE_LIBNAMES)}"
+        )
+
+
 def _coerce_subprocess_output(output: str | bytes | None) -> str:
     if isinstance(output, bytes):
         return output.decode(errors="replace")
@@ -320,11 +335,5 @@ def load_nvidia_dynamic_lib(libname: str) -> LoadedDL:
             f" Currently running: {pointer_size_bits}-bit Python"
             f" {sys.version_info.major}.{sys.version_info.minor}"
         )
-    if libname not in _ALL_KNOWN_LIBNAMES:
-        raise DynamicLibUnknownError(f"Unknown library name: {libname!r}. Known names: {sorted(_ALL_KNOWN_LIBNAMES)}")
-    if libname not in ALL_AVAILABLE_LIBNAMES:
-        raise DynamicLibNotAvailableError(
-            f"Library name {libname!r} is known but not available on {_PLATFORM_NAME}. "
-            f"Supported names on {_PLATFORM_NAME}: {sorted(ALL_AVAILABLE_LIBNAMES)}"
-        )
+    check_libname(libname)
     return _load_lib_no_cache(libname)

cuda_pathfinder/docs/source/api.rst

@@ -6,8 +6,8 @@
 ``cuda.pathfinder`` API Reference
 =================================
 
-The ``cuda.pathfinder`` module provides utilities for loading NVIDIA dynamic libraries,
-locating NVIDIA C/C++ header directories, finding CUDA binary utilities, and locating
+The ``cuda.pathfinder`` module provides utilities for loading and locating NVIDIA dynamic
+libraries, locating NVIDIA C/C++ header directories, finding CUDA binary utilities, and locating
 CUDA bitcode and static libraries.
 
 .. NOTE: The source of truth for public APIs is cuda_pathfinder/cuda/pathfinder/__init__.py.
@@ -21,6 +21,9 @@ CUDA bitcode and static libraries.
    SUPPORTED_NVIDIA_LIBNAMES
    load_nvidia_dynamic_lib
    LoadedDL
+   find_nvidia_dynamic_lib
+   locate_nvidia_dynamic_lib
+   LocatedDynamicLib
    DynamicLibNotFoundError
    DynamicLibUnknownError
    DynamicLibNotAvailableError