[srimanachanta]

Closes #757

Summary

Add locate_nvidia_dynamic_lib(libname) -> LocatedDynamicLib and find_nvidia_dynamic_lib(libname) -> str. They return the file load_nvidia_dynamic_lib would load in a fresh process, without loading it into the caller's process. The pair matches locate_static_lib/find_static_lib and locate_bitcode_lib/find_bitcode_lib.

Motivation

The only way to get a shared library's path today is load_nvidia_dynamic_lib, which loads the library to report where it is. A build backend that only needs the path pays for the load, and has to handle a LoadedDL whose abs_path is None. My downstream CUDA extension library does this in its CMake probe script: cmake/cuda_pathfinder_probe.py.

Design

• Same search steps and order as load_nvidia_dynamic_lib: site-packages, conda, native loader search, library-specific roots and CUDA_PATH/CUDA_HOME, Program Files, CTK root canary. Driver libraries use the native loader search only.
• The native loader search can only be observed by loading, so it runs in the existing canary subprocess (_resolve_system_loaded_abs_path_in_subprocess). Nothing is loaded in the caller's process.
• A library already loaded in the current process is not taken into account. This follows the discussion in [FEA]: Add find_nvidia_dynamic_library to find the DSO location without loading #757: the result is what pathfinder would find without other DSOs influencing it. The docstring says when the result can differ from load_nvidia_dynamic_lib.
• Same error contract as load_nvidia_dynamic_lib: DynamicLibUnknownError, DynamicLibNotAvailableError, DynamicLibNotFoundError.
• find_nvidia_dynamic_lib is cached with functools.cache, like find_static_lib. locate_nvidia_dynamic_lib is not.

Tests

• test_locate_matches_load_in_fresh_process: for every supported library, runs load_nvidia_dynamic_lib in a child process with the existing helper and checks that locate_nvidia_dynamic_lib in the parent returns the same file, or raises DynamicLibNotFoundError when the child finds nothing.
• Mocked tests for the search order, driver libraries, not-found errors, the find_ cache, and that no LOADER load or already-loaded check runs.
• Full pathfinder suite passes locally (Linux x86-64, CUDA 13.4 wheels plus a system CTK). The real-library test covered site-packages, system-search and not-found results.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

📝 Summary

Summary by CodeRabbit

• New Features
  • Added utilities to locate NVIDIA dynamic libraries without loading them into the current process. Results can include the absolute path, filename, and discovery method.
  • Added cached path lookup and clearer errors for unknown, unavailable, or missing libraries. Discovery checks supported search locations and required dependencies.
• Documentation
  • Updated the API reference to cover the library-location utilities and the information they return.

The change adds public functions to locate supported NVIDIA dynamic libraries without loading them into the caller’s process. The lookup follows the library search order, reports the path and discovery method, and includes a cached path-only wrapper.

Changes: Dynamic-library location

Layer / File(s)	Summary
Lookup flow and validation cuda_pathfinder/cuda/pathfinder/_dynamic_libs/find_nvidia_dynamic_lib.py, cuda_pathfinder/cuda/pathfinder/_dynamic_libs/load_nvidia_dynamic_lib.py, cuda_pathfinder/tests/test_find_nvidia_dynamic_lib.py	Adds a result type and lookup functions. The lookup checks early search steps, system search, late search steps, and the configured CTK root canary. Driver libraries use system search only. Library-name validation and driver-not-found error construction are factored into helpers. Tests cover search order, dependencies, errors, and caching.
Public API exposure cuda_pathfinder/cuda/pathfinder/__init__.py, cuda_pathfinder/docs/source/api.rst	Re-exports the result type and lookup functions, and adds them to the API reference.

Assessment against linked issues

Objective	Addressed	Explanation
[#757] Find the DSO location that the path finder would load without loading it.	✅

Possibly related issues

• [BUG]: Windows system search does use PATH, contrary to docs #3137: The lookup uses the system-loader search behavior also used by the loading path, so it may report the PATH-selected DLL described by this issue.

Possibly related PRs

• NVIDIA/cuda-python#3188: This PR updates cuDSS descriptor catalog names, which the new lookup uses to validate and locate supported libraries.

Suggested labels: enhancement

Suggested reviewers: rwgk

Priority: Normal

Change: Feature

Merge Risk: Moderate · up to 0d0bc

Path lookup can disagree with loading when a required dependency is available only outside the native loader search. Resolve that mismatch before merging; a cached native-search miss can also remain stale if library availability changes during a process’s lifetime.

Finishing Touches: 💡 1

🛠️ Fix failing CI checks: 💡

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

---

Review info

Run configuration

• Source mode: Auto
• Repository: NVIDIA/cuda-python
• Branch: main
• File: .coderabbit.yaml
• Commit: 590a8bf
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Enterprise
• Run ID: 1cd2832c-2e2c-484a-affe-5e0ddc6e9db2

Commits

Reviewing files that changed from the base of the PR and between 590a8bf and 4b9b059.

Files selected for processing: 5

• cuda_pathfinder/cuda/pathfinder/__init__.py
• cuda_pathfinder/cuda/pathfinder/_dynamic_libs/find_nvidia_dynamic_lib.py
• cuda_pathfinder/cuda/pathfinder/_dynamic_libs/load_nvidia_dynamic_lib.py
• cuda_pathfinder/docs/source/api.rst
• cuda_pathfinder/tests/test_find_nvidia_dynamic_lib.py

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

[coderabbitai]

Actionable comments posted: 1

---

Review info

Run configuration

• Source mode: Auto
• Repository: NVIDIA/cuda-python
• Branch: main
• File: .coderabbit.yaml
• Commit: 590a8bf
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Enterprise
• Run ID: 68bd366b-5449-4729-b4bb-38052612a819

Commits

Reviewing files that changed from the base of the PR and between 4b9b059 and 0d0bc80.

Files selected for processing: 2

• cuda_pathfinder/cuda/pathfinder/_dynamic_libs/find_nvidia_dynamic_lib.py
• cuda_pathfinder/tests/test_find_nvidia_dynamic_lib.py

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 10 remain after this review.

[coderabbitai]

Major · Data Integrity & Integration · Heavy lift

Supported by static analysis

Script executed:

f1=cuda_pathfinder/cuda/pathfinder/_dynamic_libs/find_nvidia_dynamic_lib.py
f2=cuda_pathfinder/cuda/pathfinder/_dynamic_libs/load_nvidia_dynamic_lib.py
ls -l "$f1" "$f2"
ast-grep outline "$f1" --view expanded
ast-grep outline "$f2" --view expanded
rg -n -F -e '_find_with_system_search' -e 'dependenc' -e 'LOADER' -- "$f1" "$f2" || test "$?" -eq 1
nl -ba "$f1" | sed -n '1,140p'

Repository: NVIDIA/cuda-python

Length of output: 10018

---

important: Locate the required dependencies in the probe subprocess before the system search.

_locate_lib locates each required dependency with locate_nvidia_dynamic_lib(dep), but it does not load it. The system-search probe then calls _resolve_system_loaded_abs_path_in_subprocess(libname), which takes only the library name and loads only that library in a fresh process. load_nvidia_dynamic_lib loads the same dependencies before its native-loader search.

When the target is reached through the system search and a required dependency exists only at a wheel path, the probe's native loader may not resolve that dependency. The probe then returns None, and _locate_lib can raise DynamicLibNotFoundError. load_nvidia_dynamic_lib can load the same target in that environment. The locate_nvidia_dynamic_lib docstring says the result is the file that load_nvidia_dynamic_lib would load in a fresh process. Its Notes list only already-loaded libraries and RPATH as sources of difference, not dependency preloading.

Pass the located dependency paths to the probe subprocess. The child should load them by absolute path before it loads the target. This keeps the caller's process unloaded. If the native-loader result is cached by library name alone, include the dependency paths in the cache key. Otherwise a cached result can be reused with a different dependency state.