[libclang/python] Add ENV variable for library_{path,file}

[TApplencourt]

Hi,

It's me again :').

I would like to address a packaging issue I faced. Currently, if libclang.so is not in a "canonical" location (i.e., in your LD_LIBRARY_PATH and named libclang.so), cindex.py will not find it by default. In those cases, one can use set_library_path and set_library_file. But this is a bit of a burden for users.

Unfortunately, in many distributions, libclang.so is named differently. On a Ubuntu 25.04 installed via apt-get, it's libclang-18.so.18; on Ubuntu LTS 24.04, it's libclang.so.1; and I imagine there are many other possible naming conventions.

To address this, the pip package for libclang patches cindex.py to support an environment variable for the library_path. Then the package manager, just export this env, and everything work "by magic" for user (it's easier than to create a symlink and modify LD_LIBRARY_PATH)

As the Spack maintainer of py-libclang, we have the same problem, and we may start patching cindex with:

class Config:
-    library_path = None
-    library_file: str | None = None
+    library_path: str | None = os.environ.get("LIBCLANG_PATH")
+    library_file: str | None = os.environ.get("LIBCLANG_FILE")
    compatibility_check = True

This will allow us to avoid patching all our Python scripts that rely on cindex (for example). Are you open for thing like that to be upstreamed?

Naming conventions:

• Pip libclang uses LIBCLANG_LIBRARY_PATH
• Rust bindgen uses LIBCLANG_PATH

I chose LIBCLANG_PATH and LIBCLANG_FILE because it's shorter...

Thanks!

[nightlark]

I was just now looking at libclang pypi patch that uses LIBCLANG_LIBRARY_PATH. I feel like since the libclang package is used quite a bit it would be better to try not to break what its users might already be using.

Perhaps both could be supported, with one taking priority over the other? If LIBCLANG_LIBRARY_PATH isn't set, check if LIBCLANG_PATH is set before giving up.