[path_finder_dev] 2025-05-01 version of cuda.bindings.path_finder

.github/workflows/test-wheel-linux.yml

@@ -189,7 +189,7 @@ jobs:
           # We don't test compute-sanitizer on CTK<12 because backporting fixes is too much effort
           # We only test compute-sanitizer on python 3.12 arbitrarily; we don't need to use sanitizer on the entire matrix
           # Only local ctk installs have compute-sanitizer; there is not wheel for it
-          if [[ "${{ inputs.python-version }}" == "3.12" && "${{ inputs.cuda-version }}" != "11.8.0" && "${{ inputs.local-ctk }}" == 1 ]]; then
+          if [[ "${{ inputs.python-version }}" == "9.99" && "${{ inputs.cuda-version }}" != "11.8.0" && "${{ inputs.local-ctk }}" == 1 ]]; then
             COMPUTE_SANITIZER="${CUDA_HOME}/bin/compute-sanitizer"
             COMPUTE_SANITIZER_VERSION=$(${COMPUTE_SANITIZER} --version | grep -Eo "[0-9]{4}\.[0-9]\.[0-9]" | sed -e 's/\.//g')
             SANITIZER_CMD="${COMPUTE_SANITIZER} --target-processes=all --launch-timeout=0 --tool=memcheck --error-exitcode=1"

cuda_bindings/cuda/bindings/_path_finder/README.md

@@ -0,0 +1,71 @@
+# `cuda.bindings.path_finder` Module
+
+## Public API (Work in Progress)
+
+Currently exposes two primary interfaces:
+
+```
+cuda.bindings.path_finder._SUPPORTED_LIBNAMES  # ('nvJitLink', 'nvrtc', 'nvvm')
+cuda.bindings.path_finder._load_nvidia_dynamic_library(libname: str) -> LoadedDL
+```
+
+**Note:**
+These APIs are prefixed with an underscore because they are considered
+experimental while undergoing active development, although already
+reasonably well-tested through CI pipelines.
+
+## Library Loading Search Priority
+
+The `load_nvidia_dynamic_library()` function implements a hierarchical search
+strategy for locating NVIDIA shared libraries:
+
+0. **Check if a library was loaded into the process already by some other means.**
+   - If yes, there is no alternative to skipping the rest of the search logic.
+     The absolute path of the already loaded library will be returned, along
+     with the handle to the library.
+
+1. **Python Package Ecosystem**
+   - Scans `sys.path` to find libraries installed via NVIDIA Python wheels.
+
+2. **Conda Environments**
+   - Leverages Conda-specific paths through our fork of `get_cuda_paths()` from Numba.
+
+3. **System Installations**
+   - Checks traditional system locations via the same `get_cuda_paths()` implementation.
+     — Note that `get_cuda_paths()` references `CUDA_HOME` and `CUDA_PATH`. The existing
+     mechanism are used as-is (see Implementation Philosophy below).
+
+4. **OS Default Mechanisms**
+   - Falls back to native loader:
+     - `dlopen()` on Linux
+     - `LoadLibraryW()` on Windows
+
+Note that the search is done on a per-library basis. There is no centralized
+mechanism that ensures all libraries are found in the same way.
+
+## Implementation Philosophy
+
+The current implementation balances stability and evolution:
+
+- **Baseline Foundation:** Uses a fork of Numba's `cuda_paths.py` that has been
+  battle-tested in production environments
+
+- **Validation Infrastructure:** Comprehensive CI testing matrix being developed to cover:
+  - Various Linux/Windows environments
+  - Python packaging formats (wheels, conda)
+  - CUDA Toolkit versions
+
+- **Roadmap:** Planned refactoring to:
+  - Unify library discovery logic
+  - Improve maintainability
+  - Better enforce search priority
+  - Expand platform support
+
+## Maintenance Requirements
+
+These key components must be updated for new CUDA Toolkit releases:
+
+- `supported_libs.SUPPORTED_LIBNAMES`
+- `supported_libs.SUPPORTED_WINDOWS_DLLS`
+- `supported_libs.SUPPORTED_LINUX_SONAMES`
+- `supported_libs.EXPECTED_LIB_SYMBOLS`