fix: improve libclang discovery on macOS and Linux

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,27 +575,52 @@ 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):
+                raise FileNotFoundError(
+                    f"LIBCLANG_PATH points to {library_file!r}, which is not a file. "
+                    "Set it to the path of libclang.dylib."
+                )
+            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"]
-            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:
@@ -600,9 +629,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 +637,23 @@ 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"]
+            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:
             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 +667,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")

tests/read_args_test.py

@@ -0,0 +1,147 @@
+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, tmp_path):
+    lib = tmp_path / "libclang.so.1"
+    lib.touch()
+    monkeypatch.setattr(mkdoc_lib, "glob", lambda _pattern: [])
+    monkeypatch.setenv("LIBCLANG_PATH", str(lib))
+
+    _, filenames = mkdoc_lib.read_args(["foo.h"])
+
+    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, tmp_path):
+    lib = tmp_path / "libclang.so.1"
+    lib.touch()
+    monkeypatch.setattr(mkdoc_lib, "glob", lambda _pattern: [])
+    monkeypatch.setenv("LIBCLANG_PATH", str(lib))
+
+    parameters, _ = mkdoc_lib.read_args(["-stdlib=libc++", "foo.h"])
+
+    assert config_calls["file"] == str(lib)
+    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("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 = {
+        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"