From 64c202ab149a0637429e750fa81b03f9026622eb Mon Sep 17 00:00:00 2001
From: Henry Schreiner <henryfs@princeton.edu>
Date: Thu, 6 Aug 2026 14:13:24 -0400
Subject: [PATCH 1/2] fix: honor LIBCLANG_PATH and Command Line Tools on macOS,
 LIBCLANG_PATH on Linux

Addresses findings 3-5 from the code review in #59:

- Linux: LIBCLANG_PATH is now consulted before raising when no
  /usr/lib*/llvm-* directory is found; llvm_dir-derived include paths
  are skipped when llvm_dir is unknown.
- macOS: honor LIBCLANG_PATH, and fall back to the Command Line Tools
  location when Xcode.app is absent (both libclang and the SDK dir).
- macOS: SDK selection is now deterministic, preferring MacOSX.sdk and
  otherwise the newest version, instead of os.walk ordering.

Assisted-by: ClaudeCode:claude-fable-5
---
 pybind11_mkdoc/mkdoc_lib.py |  77 ++++++++++++++-------
 tests/read_args_test.py     | 134 ++++++++++++++++++++++++++++++++++++
 2 files changed, 185 insertions(+), 26 deletions(-)
 create mode 100644 tests/read_args_test.py

diff --git a/pybind11_mkdoc/mkdoc_lib.py b/pybind11_mkdoc/mkdoc_lib.py
index 0a553d7..b14ca20 100755
--- a/pybind11_mkdoc/mkdoc_lib.py
+++ b/pybind11_mkdoc/mkdoc_lib.py
@@ -560,6 +560,10 @@ def _extract_file(filename, parameters):
     return output
 
 
+def _folder_version(d):
+    return [int(ver) for ver in re.findall(r"(?<!lib)(?<!\d)\d+", d)]
+
+
 def read_args(args):
     parameters = []
     filenames = []
@@ -571,18 +575,42 @@ def read_args(args):
 
     if platform.system() == "Darwin":
         dev_path = "/Applications/Xcode.app/Contents/Developer/"
-        lib_dir = dev_path + "Toolchains/XcodeDefault.xctoolchain/usr/lib/"
-        sdk_dir = dev_path + "Platforms/MacOSX.platform/Developer/SDKs"
-        libclang = lib_dir + "libclang.dylib"
+        clt_path = "/Library/Developer/CommandLineTools/"
 
         # cindex forbids (re)configuring the library once it has been loaded
-        if os.path.exists(libclang) and not cindex.Config.loaded:
-            cindex.Config.set_library_path(os.path.dirname(libclang))
-
-        if os.path.exists(sdk_dir):
-            sysroot_dir = os.path.join(sdk_dir, next(os.walk(sdk_dir))[1][0])
-            parameters.append("-isysroot")
-            parameters.append(sysroot_dir)
+        if "LIBCLANG_PATH" in os.environ:
+            library_file = os.environ["LIBCLANG_PATH"]
+            if not os.path.isfile(library_file):
+                msg = (
+                    "Failed to find libclang.dylib! Set the LIBCLANG_PATH environment variable to provide a path to it."
+                )
+                raise FileNotFoundError(msg)
+            if not cindex.Config.loaded:
+                cindex.Config.set_library_file(library_file)
+        else:
+            for libclang in (
+                dev_path + "Toolchains/XcodeDefault.xctoolchain/usr/lib/libclang.dylib",
+                clt_path + "usr/lib/libclang.dylib",
+            ):
+                if os.path.exists(libclang):
+                    if not cindex.Config.loaded:
+                        cindex.Config.set_library_path(os.path.dirname(libclang))
+                    break
+
+        for sdk_dir in (
+            dev_path + "Platforms/MacOSX.platform/Developer/SDKs",
+            clt_path + "SDKs",
+        ):
+            if os.path.exists(sdk_dir):
+                sdks = sorted(next(os.walk(sdk_dir))[1], key=_folder_version)
+                if "MacOSX.sdk" in sdks:
+                    sdk = "MacOSX.sdk"
+                elif sdks:
+                    sdk = sdks[-1]
+                else:
+                    continue
+                parameters.extend(["-isysroot", os.path.join(sdk_dir, sdk)])
+                break
     elif platform.system() == "Windows":
         if "LIBCLANG_PATH" in os.environ:
             library_file = os.environ["LIBCLANG_PATH"]
@@ -600,9 +628,6 @@ def read_args(args):
         # LLVM switched to a monolithical setup that includes everything under
         # /usr/lib/llvm{version_number}/. We glob for the library and select
         # the highest version
-        def folder_version(d):
-            return [int(ver) for ver in re.findall(r"(?<!lib)(?<!\d)\d+", d)]
-
         llvm_dir = max(
             (
                 path
@@ -611,13 +636,18 @@ def folder_version(d):
                 if os.path.exists(os.path.join(path, "lib", "libclang.so.1"))
             ),
             default=None,
-            key=folder_version,
+            key=_folder_version,
         )
 
         # Ability to override LLVM/libclang paths
         if "LLVM_DIR_PATH" in os.environ:
             llvm_dir = os.environ["LLVM_DIR_PATH"]
-        elif llvm_dir is None:
+
+        if "LIBCLANG_PATH" in os.environ:
+            libclang_file = os.environ["LIBCLANG_PATH"]
+        elif llvm_dir is not None:
+            libclang_file = os.path.join(llvm_dir, "lib", "libclang.so.1")
+        else:
             msg = (
                 "Failed to find a LLVM installation providing the file "
                 "/usr/lib{32,64}/llvm-{VER}/lib/libclang.so.1. Make sure that "
@@ -631,29 +661,24 @@ def folder_version(d):
             )
             raise FileNotFoundError(msg)
 
-        if "LIBCLANG_PATH" in os.environ:
-            libclang_dir = os.environ["LIBCLANG_PATH"]
-        else:
-            libclang_dir = os.path.join(llvm_dir, "lib", "libclang.so.1")
-
         if not cindex.Config.loaded:
-            cindex.Config.set_library_file(libclang_dir)
+            cindex.Config.set_library_file(libclang_file)
         cpp_dirs = []
 
         if "-stdlib=libc++" not in args:
-            cpp_dirs.append(max(glob("/usr/include/c++/*"), default=None, key=folder_version))
+            cpp_dirs.append(max(glob("/usr/include/c++/*"), default=None, key=_folder_version))
 
             cpp_dirs.append(
-                max(glob(f"/usr/include/{platform.machine()}-linux-gnu/c++/*"), default=None, key=folder_version)
+                max(glob(f"/usr/include/{platform.machine()}-linux-gnu/c++/*"), default=None, key=_folder_version)
             )
-        else:
+        elif llvm_dir is not None:
             cpp_dirs.append(os.path.join(llvm_dir, "include", "c++", "v1"))
 
         if "CLANG_INCLUDE_DIR" in os.environ:
             cpp_dirs.append(os.environ["CLANG_INCLUDE_DIR"])
-        else:
+        elif llvm_dir is not None:
             cpp_dirs.append(
-                max(glob(os.path.join(llvm_dir, "lib", "clang", "*", "include")), default=None, key=folder_version)
+                max(glob(os.path.join(llvm_dir, "lib", "clang", "*", "include")), default=None, key=_folder_version)
             )
 
         cpp_dirs.append(f"/usr/include/{platform.machine()}-linux-gnu")
diff --git a/tests/read_args_test.py b/tests/read_args_test.py
new file mode 100644
index 0000000..472b276
--- /dev/null
+++ b/tests/read_args_test.py
@@ -0,0 +1,134 @@
+import os
+
+import pytest
+from clang import cindex
+
+from pybind11_mkdoc import mkdoc_lib
+
+CLT = "/Library/Developer/CommandLineTools/"
+XCODE = "/Applications/Xcode.app/Contents/Developer/"
+
+
+@pytest.fixture
+def config_calls(monkeypatch):
+    """Record cindex.Config.set_library_* calls instead of configuring libclang."""
+    calls = {}
+    monkeypatch.setattr(cindex.Config, "loaded", False)
+    monkeypatch.setattr(cindex.Config, "set_library_file", lambda p: calls.__setitem__("file", p))
+    monkeypatch.setattr(cindex.Config, "set_library_path", lambda p: calls.__setitem__("path", p))
+    return calls
+
+
+@pytest.fixture
+def clean_env(monkeypatch):
+    for var in ["LIBCLANG_PATH", "LLVM_DIR_PATH", "CLANG_INCLUDE_DIR", "CPP_INCLUDE_DIRS"]:
+        monkeypatch.delenv(var, raising=False)
+
+
+@pytest.fixture
+def linux(monkeypatch):
+    monkeypatch.setattr(mkdoc_lib.platform, "system", lambda: "Linux")
+
+
+@pytest.fixture
+def darwin(monkeypatch):
+    monkeypatch.setattr(mkdoc_lib.platform, "system", lambda: "Darwin")
+
+
+def fake_walk(subdirs):
+    return lambda top: iter([(top, list(subdirs), [])])
+
+
+@pytest.mark.usefixtures("linux", "clean_env")
+def test_linux_libclang_path_without_llvm_dir(monkeypatch, config_calls):
+    monkeypatch.setattr(mkdoc_lib, "glob", lambda _pattern: [])
+    monkeypatch.setenv("LIBCLANG_PATH", "/opt/lib/libclang.so.1")
+
+    _, filenames = mkdoc_lib.read_args(["foo.h"])
+
+    assert config_calls["file"] == "/opt/lib/libclang.so.1"
+    assert filenames == ["foo.h"]
+
+
+@pytest.mark.usefixtures("linux", "clean_env")
+def test_linux_libclang_path_without_llvm_dir_libcpp(monkeypatch, config_calls):
+    monkeypatch.setattr(mkdoc_lib, "glob", lambda _pattern: [])
+    monkeypatch.setenv("LIBCLANG_PATH", "/opt/lib/libclang.so.1")
+
+    parameters, _ = mkdoc_lib.read_args(["-stdlib=libc++", "foo.h"])
+
+    assert config_calls["file"] == "/opt/lib/libclang.so.1"
+    assert "-stdlib=libc++" in parameters
+
+
+@pytest.mark.usefixtures("linux", "clean_env", "config_calls")
+def test_linux_no_llvm_dir_no_env_raises(monkeypatch):
+    monkeypatch.setattr(mkdoc_lib, "glob", lambda _pattern: [])
+
+    with pytest.raises(FileNotFoundError):
+        mkdoc_lib.read_args(["foo.h"])
+
+
+@pytest.mark.usefixtures("darwin", "clean_env")
+def test_macos_xcode_preferred(monkeypatch, config_calls):
+    existing = {
+        XCODE + "Toolchains/XcodeDefault.xctoolchain/usr/lib/libclang.dylib",
+        XCODE + "Platforms/MacOSX.platform/Developer/SDKs",
+        CLT + "usr/lib/libclang.dylib",
+        CLT + "SDKs",
+    }
+    monkeypatch.setattr(os.path, "exists", lambda p: p in existing)
+    monkeypatch.setattr(os, "walk", fake_walk(["MacOSX.sdk"]))
+
+    parameters, _ = mkdoc_lib.read_args(["foo.h"])
+
+    assert config_calls["path"] == XCODE + "Toolchains/XcodeDefault.xctoolchain/usr/lib"
+    idx = parameters.index("-isysroot")
+    assert parameters[idx + 1] == XCODE + "Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk"
+
+
+@pytest.mark.usefixtures("darwin", "clean_env")
+def test_macos_command_line_tools_fallback(monkeypatch, config_calls):
+    existing = {CLT + "usr/lib/libclang.dylib", CLT + "SDKs"}
+    monkeypatch.setattr(os.path, "exists", lambda p: p in existing)
+    monkeypatch.setattr(os, "walk", fake_walk(["MacOSX.sdk", "MacOSX26.0.sdk"]))
+
+    parameters, _ = mkdoc_lib.read_args(["foo.h"])
+
+    assert config_calls["path"] == CLT + "usr/lib"
+    idx = parameters.index("-isysroot")
+    assert parameters[idx + 1] == CLT + "SDKs/MacOSX.sdk"
+
+
+@pytest.mark.usefixtures("darwin", "clean_env")
+def test_macos_libclang_path_env(monkeypatch, config_calls, tmp_path):
+    lib = tmp_path / "libclang.dylib"
+    lib.touch()
+    monkeypatch.setenv("LIBCLANG_PATH", str(lib))
+    monkeypatch.setattr(os.path, "exists", lambda _p: False)
+
+    parameters, _ = mkdoc_lib.read_args(["foo.h"])
+
+    assert config_calls["file"] == str(lib)
+    assert "-isysroot" not in parameters
+
+
+@pytest.mark.usefixtures("darwin", "clean_env", "config_calls")
+def test_macos_libclang_path_env_missing_raises(monkeypatch, tmp_path):
+    monkeypatch.setenv("LIBCLANG_PATH", str(tmp_path / "does_not_exist.dylib"))
+
+    with pytest.raises(FileNotFoundError):
+        mkdoc_lib.read_args(["foo.h"])
+
+
+@pytest.mark.usefixtures("darwin", "clean_env", "config_calls")
+def test_macos_sdk_newest_numeric(monkeypatch):
+    existing = {CLT + "usr/lib/libclang.dylib", CLT + "SDKs"}
+    monkeypatch.setattr(os.path, "exists", lambda p: p in existing)
+    # No MacOSX.sdk; lexical sort would wrongly pick MacOSX9.sdk as newest
+    monkeypatch.setattr(os, "walk", fake_walk(["MacOSX9.sdk", "MacOSX10.1.sdk"]))
+
+    parameters, _ = mkdoc_lib.read_args(["foo.h"])
+
+    idx = parameters.index("-isysroot")
+    assert parameters[idx + 1] == CLT + "SDKs/MacOSX10.1.sdk"

From 4e820eb25c600236b503db7b9c1b0ea823657a71 Mon Sep 17 00:00:00 2001
From: Henry Schreiner <henryfs@princeton.edu>
Date: Fri, 7 Aug 2026 08:56:19 -0400
Subject: [PATCH 2/2] fix: validate LIBCLANG_PATH on Linux and report the path
 in errors

Assisted-by: ClaudeCode:claude-opus-5
---
 pybind11_mkdoc/mkdoc_lib.py | 24 +++++++++++++++---------
 tests/read_args_test.py     | 25 +++++++++++++++++++------
 2 files changed, 34 insertions(+), 15 deletions(-)

diff --git a/pybind11_mkdoc/mkdoc_lib.py b/pybind11_mkdoc/mkdoc_lib.py
index b14ca20..7e5733d 100755
--- a/pybind11_mkdoc/mkdoc_lib.py
+++ b/pybind11_mkdoc/mkdoc_lib.py
@@ -581,10 +581,10 @@ def read_args(args):
         if "LIBCLANG_PATH" in os.environ:
             library_file = os.environ["LIBCLANG_PATH"]
             if not os.path.isfile(library_file):
-                msg = (
-                    "Failed to find libclang.dylib! Set the LIBCLANG_PATH environment variable to provide a path to it."
+                raise FileNotFoundError(
+                    f"LIBCLANG_PATH points to {library_file!r}, which is not a file. "
+                    "Set it to the path of libclang.dylib."
                 )
-                raise FileNotFoundError(msg)
             if not cindex.Config.loaded:
                 cindex.Config.set_library_file(library_file)
         else:
@@ -614,12 +614,13 @@ def read_args(args):
     elif platform.system() == "Windows":
         if "LIBCLANG_PATH" in os.environ:
             library_file = os.environ["LIBCLANG_PATH"]
-            if os.path.isfile(library_file):
-                if not cindex.Config.loaded:
-                    cindex.Config.set_library_file(library_file)
-            else:
-                msg = "Failed to find libclang.dll! Set the LIBCLANG_PATH environment variable to provide a path to it."
-                raise FileNotFoundError(msg)
+            if not os.path.isfile(library_file):
+                raise FileNotFoundError(
+                    f"LIBCLANG_PATH points to {library_file!r}, which is not a file. "
+                    "Set it to the path of libclang.dll."
+                )
+            if not cindex.Config.loaded:
+                cindex.Config.set_library_file(library_file)
         else:
             library_file = ctypes.util.find_library("libclang.dll")
             if library_file is not None and not cindex.Config.loaded:
@@ -645,6 +646,11 @@ def read_args(args):
 
         if "LIBCLANG_PATH" in os.environ:
             libclang_file = os.environ["LIBCLANG_PATH"]
+            if not os.path.isfile(libclang_file):
+                raise FileNotFoundError(
+                    f"LIBCLANG_PATH points to {libclang_file!r}, which is not a file. "
+                    "Set it to the path of libclang.so.1."
+                )
         elif llvm_dir is not None:
             libclang_file = os.path.join(llvm_dir, "lib", "libclang.so.1")
         else:
diff --git a/tests/read_args_test.py b/tests/read_args_test.py
index 472b276..9424f29 100644
--- a/tests/read_args_test.py
+++ b/tests/read_args_test.py
@@ -40,24 +40,28 @@ def fake_walk(subdirs):
 
 
 @pytest.mark.usefixtures("linux", "clean_env")
-def test_linux_libclang_path_without_llvm_dir(monkeypatch, config_calls):
+def test_linux_libclang_path_without_llvm_dir(monkeypatch, config_calls, tmp_path):
+    lib = tmp_path / "libclang.so.1"
+    lib.touch()
     monkeypatch.setattr(mkdoc_lib, "glob", lambda _pattern: [])
-    monkeypatch.setenv("LIBCLANG_PATH", "/opt/lib/libclang.so.1")
+    monkeypatch.setenv("LIBCLANG_PATH", str(lib))
 
     _, filenames = mkdoc_lib.read_args(["foo.h"])
 
-    assert config_calls["file"] == "/opt/lib/libclang.so.1"
+    assert config_calls["file"] == str(lib)
     assert filenames == ["foo.h"]
 
 
 @pytest.mark.usefixtures("linux", "clean_env")
-def test_linux_libclang_path_without_llvm_dir_libcpp(monkeypatch, config_calls):
+def test_linux_libclang_path_without_llvm_dir_libcpp(monkeypatch, config_calls, tmp_path):
+    lib = tmp_path / "libclang.so.1"
+    lib.touch()
     monkeypatch.setattr(mkdoc_lib, "glob", lambda _pattern: [])
-    monkeypatch.setenv("LIBCLANG_PATH", "/opt/lib/libclang.so.1")
+    monkeypatch.setenv("LIBCLANG_PATH", str(lib))
 
     parameters, _ = mkdoc_lib.read_args(["-stdlib=libc++", "foo.h"])
 
-    assert config_calls["file"] == "/opt/lib/libclang.so.1"
+    assert config_calls["file"] == str(lib)
     assert "-stdlib=libc++" in parameters
 
 
@@ -69,6 +73,15 @@ def test_linux_no_llvm_dir_no_env_raises(monkeypatch):
         mkdoc_lib.read_args(["foo.h"])
 
 
+@pytest.mark.usefixtures("linux", "clean_env", "config_calls")
+def test_linux_libclang_path_missing_raises(monkeypatch, tmp_path):
+    monkeypatch.setattr(mkdoc_lib, "glob", lambda _pattern: [])
+    monkeypatch.setenv("LIBCLANG_PATH", str(tmp_path / "does_not_exist.so.1"))
+
+    with pytest.raises(FileNotFoundError):
+        mkdoc_lib.read_args(["foo.h"])
+
+
 @pytest.mark.usefixtures("darwin", "clean_env")
 def test_macos_xcode_preferred(monkeypatch, config_calls):
     existing = {