WIP: Replace cuda_paths.py to achieve desired Search Priority — toolshed/run_cuda_bindings_path_finder.py passes but tests/test_path_finder_find_load.py does not.

Author: rwgk

cuda_bindings/cuda/bindings/_path_finder/README.md

@@ -25,7 +25,8 @@ strategy for locating NVIDIA shared libraries:
      with the handle to the library.
 
 1. **Environment variables**
-   - Relies on `CUDA_HOME`/`CUDA_PATH` environment variables if set.
+   - Relies on `CUDA_HOME` or `CUDA_PATH` environment variables if set
+     (in that order).
 
 2. **NVIDIA Python wheels**
    - Scans all site-packages to find libraries installed via NVIDIA Python wheels.
@@ -34,41 +35,16 @@ strategy for locating NVIDIA shared libraries:
    - Falls back to native loader:
      - `dlopen()` on Linux
      - `LoadLibraryW()` on Windows
-   - Conda environments are expected to be covered by OS default mechanisms:
-     - Based on `$ORIGIN/../lib` `RPATH` on Linux
-     - Based on `%CONDA_PREFIX%\Library\bin` on the system `PATH` on Windows
-
-5. **System Installations**
-   - Checks traditional system locations through these paths:
-     - Linux: `/usr/local/cuda/lib64`
-     - Windows: `C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\vX.Y\bin`
-       (where X.Y is the CTK version)
-   - **Notably does NOT search**:
-     - Versioned CUDA directories like `/usr/local/cuda-12.3`
-     - Distribution-specific packages (RPM/DEB)
-       EXCEPT Debian's `nvidia-cuda-toolkit`
+   - CTK installations with system config updates are expected to be discovered:
+     - Linux: Via `/etc/ld.so.conf.d/*cuda*.conf`
+     - Windows: Via `C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\vX.Y\bin` on system `PATH`
+   - Conda installations are expected to be discovered:
+     - Linux: Via `$ORIGIN/../lib` on `RPATH` (of the `python` binary)
+     - Windows: Via `%CONDA_PREFIX%\Library\bin` on system `PATH`
 
 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-cuda'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: