fix: improve libclang discovery on macOS and Linux

.github/workflows/ci.yml

@@ -42,36 +42,29 @@ jobs:
     - name: Test package
       run: uv run --with "clang<19" --group test pytest
 
-# Commented for now -- msys2 Clang (v15) and the clang Python package (v14) are incompatible
-#
-#  checks_windows:
-#    strategy:
-#      fail-fast: false
-#      matrix:
-#        python-version:
-#        - "3.8"
-#        - "3.9"
-#        runs-on:
-#        - windows-latest
-#    runs-on: ${{ matrix.runs-on }}
-#    name: Test • 🐍 ${{ matrix.python-version }} • ${{matrix.runs-on}}
-#    steps:
-#    - uses: actions/checkout@v7
-#    - uses: actions/setup-python@v7
-#      with:
-#        python-version: ${{ matrix.python-version }}
-#
-#    - name: Install package
-#      run: python -m pip install -e. --group test
-#
-#    - name: Install clang
-#      run: C:\msys64\usr\bin\pacman.exe -S clang64/mingw-w64-clang-x86_64-clang --noconfirm
-#
-#    - name: Test package
-#      env:
-#        LIBCLANG_PATH: C:\msys64\clang64\bin\libclang.dll 
-#      run: python -m pytest -n2
-
+  checks_windows:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+        - "3.9"
+        - "3.14"
+    runs-on: windows-latest
+    name: Test • 🐍 ${{ matrix.python-version }} • windows-latest
+    steps:
+    - uses: actions/checkout@v7
+    - uses: actions/setup-python@v7
+      with:
+        python-version: ${{ matrix.python-version }}
+        allow-prereleases: true
+    - uses: astral-sh/setup-uv@v9.0.0
+
+    - name: Test package
+      env:
+        LIBCLANG_PATH: C:\Program Files\LLVM\bin\libclang.dll
+      run: uv run --with "clang<19" --group test pytest
+
+
   dist:
     runs-on: ubuntu-latest
     name: Build distribution

pybind11_mkdoc/mkdoc_lib.py

@@ -17,6 +17,7 @@
 from concurrent.futures import ThreadPoolExecutor
 from glob import glob
 from itertools import repeat
+from pathlib import PurePosixPath
 
 from clang import cindex
 from clang.cindex import CursorKind
@@ -577,6 +578,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 = []
@@ -588,27 +593,54 @@ 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 = (
+                    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:
+            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", str(PurePosixPath(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."
+            if not os.path.isfile(library_file):
+                msg = (
+                    f"LIBCLANG_PATH points to {library_file!r}, which is not a file. "
+                    "Set it to the path of libclang.dll."
+                )
                 raise FileNotFoundError(msg)
+            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:
@@ -617,24 +649,32 @@ 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
                 for libdir in ["lib64", "lib", "lib32"]
                 for path in glob(f"/usr/{libdir}/llvm-*")
-                if os.path.exists(os.path.join(path, "lib", "libclang.so.1"))
+                if os.path.exists(str(PurePosixPath(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):
+                msg = (
+                    f"LIBCLANG_PATH points to {libclang_file!r}, which is not a file. "
+                    "Set it to the path of libclang.so.1."
+                )
+                raise FileNotFoundError(msg)
+        elif llvm_dir is not None:
+            libclang_file = str(PurePosixPath(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 "
@@ -648,29 +688,28 @@ 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:
-            cpp_dirs.append(os.path.join(llvm_dir, "include", "c++", "v1"))
+        elif llvm_dir is not None:
+            cpp_dirs.append(str(PurePosixPath(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(str(PurePosixPath(llvm_dir) / "lib" / "clang" / "*" / "include")),
+                    default=None,
+                    key=_folder_version,
+                )
             )
 
         cpp_dirs.append(f"/usr/include/{platform.machine()}-linux-gnu")