Skip to content

Commit d93a33c

Browse files
authored
docs(pathfinder): correct Windows DLL search contract (#3435)
* docs(pathfinder): correct Windows DLL search contract Signed-off-by: Ralf W. Grosse-Kunstleve <[email protected]> * test(pathfinder): cover native search precedence Signed-off-by: Ralf W. Grosse-Kunstleve <[email protected]> * docs(pathfinder): clarify release note and test provenance Signed-off-by: Ralf W. Grosse-Kunstleve <[email protected]> * docs(pathfinder): refine canary and Windows search wording --------- Signed-off-by: Ralf W. Grosse-Kunstleve <[email protected]>
1 parent 96fdba6 commit d93a33c

7 files changed

Lines changed: 164 additions & 32 deletions

File tree

‎cuda_pathfinder/cuda/pathfinder/_dynamic_libs/load_dl_windows.py‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -136,11 +136,12 @@ def check_if_already_loaded_from_elsewhere(desc: LibDescriptor) -> LoadedDL | No
136136
def load_with_system_search(desc: LibDescriptor) -> LoadedDL | None:
137137
"""Try to load a DLL using the native Windows process DLL search path.
138138
139-
This calls ``LoadLibraryExW(dll_name, NULL, 0)`` directly. Under Python
140-
3.8+, CPython configures the process with
141-
``SetDefaultDllDirectories(LOAD_LIBRARY_SEARCH_DEFAULT_DIRS)``, so this
142-
search does **not** include the system ``PATH``. Directories added via
143-
``AddDllDirectory()`` still participate.
139+
This calls ``LoadLibraryExW(dll_name, NULL, 0)`` directly. For an ordinary
140+
unpackaged process, native DLL search includes ``PATH`` unless a different
141+
process DLL search policy has been configured. The restricted defaults
142+
used by Python's own loading mechanisms do not override this native call.
143+
Directories added via ``AddDllDirectory()`` participate only if the process
144+
defaults include ``LOAD_LIBRARY_SEARCH_USER_DIRS``.
144145
145146
Args:
146147
desc: Descriptor for the library to load

‎cuda_pathfinder/cuda/pathfinder/_dynamic_libs/load_nvidia_dynamic_lib.py‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -259,27 +259,26 @@ def load_nvidia_dynamic_lib(libname: str) -> LoadedDL:
259259
260260
- Fall back to the native loader:
261261
262-
- Linux: ``dlopen()``
262+
- Linux: ``dlopen()``. CUDA Toolkit (CTK) system installs may be
263+
discovered via ``LD_LIBRARY_PATH`` or linker configuration such
264+
as ``/etc/ld.so.conf.d/*cuda*.conf``.
263265
264-
- Windows: ``LoadLibraryExW()``
265-
266-
On Linux, CUDA Toolkit (CTK) system installs with system config updates are
267-
usually discovered via ``/etc/ld.so.conf.d/*cuda*.conf``.
268-
269-
On Windows, under Python 3.8+, CPython configures the process with
270-
``SetDefaultDllDirectories(LOAD_LIBRARY_SEARCH_DEFAULT_DIRS)``.
271-
As a result, the native DLL search used here does **not** include
272-
the system ``PATH``.
266+
- Windows: ``LoadLibraryExW(dll_name, NULL, 0)``. For an ordinary
267+
unpackaged process, native DLL search includes ``PATH`` unless
268+
a different process DLL search policy has been configured.
269+
Python's restricted defaults for its own loads do not override
270+
this native call.
273271
274272
4. **Environment variables**
275273
276274
- First search library-specific roots declared by the descriptor,
277275
such as ``CUDNN_PATH`` and ``NCCL_HOME``, using their
278276
platform-specific product layouts. Then use ``CUDA_PATH`` or
279277
``CUDA_HOME`` (in that order).
280-
On Windows, ``CUDA_PATH`` is the typical way system-installed CTK
281-
DLLs are located. Note that the NVIDIA CTK installer automatically
282-
adds ``CUDA_PATH`` to the system-wide environment.
278+
These are fallback discovery locations, not runtime toolkit
279+
selectors: libraries found by earlier steps take precedence.
280+
On Windows, the NVIDIA CTK installer automatically adds
281+
``CUDA_PATH`` to the system-wide environment.
283282
284283
5. **Windows Program Files (configured libraries only)**
285284
@@ -290,11 +289,12 @@ def load_nvidia_dynamic_lib(libname: str) -> LoadedDL:
290289
6. **CTK root canary probe (discoverable libs only)**
291290
292291
- For selected libraries whose shared object doesn't reside on the
293-
standard linker path (currently ``nvvm``), attempt to derive CTK
294-
root by system-loading a well-known CTK canary library in a
295-
subprocess and then searching relative to that root. On Windows,
296-
the canary uses the same native ``LoadLibraryExW`` semantics as
297-
step 3, so there is also no ``PATH``-based discovery.
292+
standard linker path (such as ``nvvm`` and ``cupti``), attempt to
293+
derive CTK root by system-loading a well-known CTK canary library
294+
in a subprocess and then searching relative to that root. On Windows,
295+
the canary uses the same native ``LoadLibraryExW(..., 0)``
296+
semantics as step 3, so it can discover libraries through
297+
``PATH`` subject to the child process's DLL search policy.
298298
299299
**Driver libraries** (``"cuda"``, ``"nvml"``):
300300

‎cuda_pathfinder/cuda/pathfinder/_dynamic_libs/search_steps.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -227,12 +227,12 @@ def find_in_install_root_env_vars(ctx: SearchContext) -> FindResult | None:
227227

228228

229229
def find_in_cuda_path(ctx: SearchContext) -> FindResult | None:
230-
"""Search ``$CUDA_PATH`` / ``$CUDA_HOME``.
230+
"""Search ``$CUDA_PATH`` / ``$CUDA_HOME`` as fallback toolkit roots.
231231
232-
On Windows, this is the normal fallback for system-installed CTK DLLs when
233-
they are not already discoverable via the native ``LoadLibraryExW(..., 0)``
234-
path used by :func:`cuda.pathfinder._dynamic_libs.load_dl_windows.load_with_system_search`.
235-
Python 3.8+ does not include ``PATH`` in that native DLL search.
232+
This step runs after native system search on both platforms. On Windows,
233+
native ``LoadLibraryExW(..., 0)`` search can already discover CTK DLLs
234+
through ``PATH``, subject to the process's DLL search policy. These roots
235+
do not override earlier discoveries or pin the runtime toolkit.
236236
237237
The returned ``found_via`` is always ``"CUDA_PATH"`` regardless of which
238238
environment variable actually provided the value.

‎cuda_pathfinder/docs/source/release/1.4.4-notes.rst‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,15 @@ Highlights
1212
* Support cusparseLt release 0.9.0 (wheels have new directory structure).
1313
(`PR #1806 <https://github.com/NVIDIA/cuda-python/pull/1806>`_)
1414

15-
* Clarified that Python 3.8+ excludes ``PATH`` from the native Windows DLL
16-
search used by ``load_nvidia_dynamic_lib()``, so CTK installs are typically
17-
found via ``CUDA_PATH``/``CUDA_HOME`` or other explicit search steps instead.
15+
* Updated the Windows DLL search documentation.
1816
(`PR #1795 <https://github.com/NVIDIA/cuda-python/pull/1795>`_)
17+
18+
.. note::
19+
20+
**Correction in 1.9.0:** The 1.4.4 release updated the documentation
21+
to incorrectly state that Python 3.8+ excludes ``PATH`` from the native
22+
Windows DLL search. The direct ``LoadLibraryExW(..., 0)`` call normally
23+
includes ``PATH`` for unpackaged processes, subject to process DLL search
24+
policy. This was a documentation error; the update did not change DLL
25+
loading behavior.
26+
(`Issue #3137 <https://github.com/NVIDIA/cuda-python/issues/3137>`_)

‎cuda_pathfinder/docs/source/release/1.9.0-notes.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,3 +33,14 @@ Bugfixes
3333
these roots lexically into a different location.
3434
(`Issue #3413 <https://github.com/NVIDIA/cuda-python/issues/3413>`_,
3535
`PR #3418 <https://github.com/NVIDIA/cuda-python/pull/3418>`_)
36+
37+
Documentation
38+
-------------
39+
40+
* Correct the Windows DLL search documentation: native system search normally
41+
includes ``PATH``, subject to process DLL search policy
42+
(`packaged applications have a different default DLL search order
43+
<https://learn.microsoft.com/en-us/windows/win32/dlls/dynamic-link-library-search-order#search-order-for-packaged-apps>`_).
44+
``CUDA_PATH`` and ``CUDA_HOME`` remain fallback discovery roots, not runtime
45+
toolkit selectors. Loading behavior and search order are unchanged.
46+
(`Issue #3137 <https://github.com/NVIDIA/cuda-python/issues/3137>`_)

‎cuda_pathfinder/tests/test_load_dl_windows.py‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,13 @@
11
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
22
# SPDX-License-Identifier: Apache-2.0
33

4+
import json
5+
import os
6+
import shutil
7+
import subprocess
48
import sys
9+
import uuid
10+
from pathlib import Path
511

612
import pytest
713

@@ -12,6 +18,51 @@
1218
from cuda.pathfinder._dynamic_libs.lib_descriptor import LIB_DESCRIPTORS
1319

1420

21+
@pytest.mark.agent_authored(model="gpt-6.1-sol")
22+
def test_system_search_finds_dll_exposed_only_through_path(tmp_path, info_summary_append):
23+
dll_name = f"cuda_pathfinder_probe_{uuid.uuid4().hex}.dll"
24+
dll_dir = tmp_path / "path_only"
25+
dll_dir.mkdir()
26+
dll_path = dll_dir / dll_name
27+
shutil.copyfile(Path(os.environ["SYSTEMROOT"], "System32", "version.dll"), dll_path)
28+
probe = """\
29+
import json
30+
import sys
31+
from dataclasses import replace
32+
33+
from cuda.pathfinder._dynamic_libs import load_dl_windows
34+
from cuda.pathfinder._dynamic_libs.lib_descriptor import LIB_DESCRIPTORS
35+
36+
desc = replace(LIB_DESCRIPTORS["cublasLt"], windows_dlls=(sys.argv[1],))
37+
loaded = load_dl_windows.load_with_system_search(desc)
38+
print(json.dumps(None if loaded is None else {
39+
"abs_path": loaded.abs_path,
40+
"found_via": loaded.found_via,
41+
}))
42+
"""
43+
44+
def run_probe(env):
45+
result = subprocess.run( # noqa: S603 - trusted interpreter, test-owned script and DLL filename
46+
[sys.executable, "-c", probe, dll_name],
47+
check=True,
48+
capture_output=True,
49+
text=True,
50+
env=env,
51+
cwd=tmp_path,
52+
timeout=30,
53+
)
54+
return json.loads(result.stdout)
55+
56+
env = os.environ.copy()
57+
assert run_probe(env) is None
58+
env["PATH"] = os.pathsep.join((str(dll_dir), env.get("PATH", "")))
59+
loaded = run_probe(env)
60+
61+
assert loaded["found_via"] == "system-search"
62+
assert os.path.samefile(loaded["abs_path"], dll_path)
63+
info_summary_append(f"PATH-only DLL: abs_path={loaded['abs_path']!r}")
64+
65+
1566
@pytest.mark.agent_authored(model="gpt-5.6-sol")
1667
def test_already_loaded_library_checks_known_dlls_in_preference_order(mocker):
1768
desc = LIB_DESCRIPTORS["cublasLt"]

‎cuda_pathfinder/tests/test_load_nvidia_dynamic_lib_using_mocker.py‎

Lines changed: 62 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
22
# SPDX-License-Identifier: Apache-2.0
33

4+
from pathlib import Path
5+
46
import pytest
57

68
from cuda.pathfinder._dynamic_libs import load_nvidia_dynamic_lib as load_mod
@@ -163,10 +165,69 @@ def _run_find_steps_disabled(ctx, steps):
163165

164166

165167
# ---------------------------------------------------------------------------
166-
# Search order tests (Conda-specific, since Conda is not covered by real CI)
168+
# Search order tests
167169
# ---------------------------------------------------------------------------
168170

169171

172+
@pytest.mark.parametrize("preferred_source", ("site-packages", "conda", "system-search"))
173+
@pytest.mark.agent_authored(model="gpt-6.1-sol")
174+
def test_cuda_path_is_a_fallback_to_environment_and_native_search(tmp_path, mocker, monkeypatch, preferred_source):
175+
desc = load_mod.LIB_DESCRIPTORS["cublasLt"]
176+
platform = steps_mod.PLATFORM
177+
filename = desc.windows_dlls[0] if IS_WINDOWS else desc.linux_sonames[0]
178+
179+
def create_library(root, relative_dir):
180+
path = root / relative_dir / filename
181+
path.parent.mkdir(parents=True, exist_ok=True)
182+
path.touch()
183+
return path
184+
185+
cuda_root = tmp_path / "toolkit"
186+
create_library(cuda_root, platform.anchor_rel_dirs(desc)[0])
187+
mocker.patch(f"{_STEPS_MODULE}.get_cuda_path_or_home", return_value=str(cuda_root))
188+
189+
conda_root = tmp_path / "conda"
190+
conda_anchor = Path(platform.conda_anchor_point(str(conda_root)))
191+
conda_path = create_library(conda_anchor, platform.anchor_rel_dirs(desc)[0])
192+
if preferred_source == "system-search":
193+
monkeypatch.delenv("CONDA_PREFIX", raising=False)
194+
else:
195+
monkeypatch.setenv("CONDA_PREFIX", str(conda_root))
196+
197+
wheel_root = tmp_path / "wheels"
198+
wheel_path = create_library(wheel_root, platform.site_packages_rel_dirs(desc)[0])
199+
200+
def find_wheel_dirs(sub_dirs):
201+
directory = wheel_root.joinpath(*sub_dirs)
202+
return [str(directory)] if preferred_source == "site-packages" and directory.is_dir() else []
203+
204+
mocker.patch(
205+
"cuda.pathfinder._dynamic_libs.search_platform.find_sub_dirs_all_sitepackages",
206+
side_effect=find_wheel_dirs,
207+
)
208+
mocker.patch.object(load_mod.LOADER, "check_if_already_loaded_from_elsewhere", return_value=None)
209+
mocker.patch(f"{_MODULE}.load_dependencies")
210+
native_path = tmp_path / "native" / filename
211+
native_search = mocker.patch.object(
212+
load_mod.LOADER,
213+
"load_with_system_search",
214+
return_value=_make_loaded_dl(str(native_path), "system-search"),
215+
)
216+
mocker.patch.object(
217+
load_mod.LOADER,
218+
"load_with_abs_path",
219+
side_effect=lambda _desc, path, via: _make_loaded_dl(path, via),
220+
)
221+
222+
loaded = _load_lib_no_cache("cublasLt")
223+
224+
expected_path = {"site-packages": wheel_path, "conda": conda_path, "system-search": native_path}[preferred_source]
225+
assert loaded.found_via == preferred_source
226+
assert loaded.abs_path == str(expected_path)
227+
if preferred_source != "system-search":
228+
native_search.assert_not_called()
229+
230+
170231
def test_cupti_search_order_conda_before_cuda_home(tmp_path, mocker, monkeypatch):
171232
"""Test that conda is searched before CUDA_HOME (CTK).
172233

0 commit comments

Comments
 (0)