Repository files navigation

Rust bindings forlibclang.

If you are interested in a somewhat idiomatic Rust wrapper for these bindings, seeclang-rs.

Released under the Apache License 2.0.

Note that the documentation onhttps://docs.rs for this crate assumes usage of theruntime Cargo feature as well as the Cargo feature for the latest supported version oflibclang (e.g.,clang_16_0), neither of which are enabled by default.

Due to the usage of theruntime Cargo feature, this documentation will contain some additional types and functions to manage a dynamically loadedlibclang instance at runtime.

Due to the usage of the Cargo feature for the latest supported version oflibclang, this documentation will contain constants and functions that are not available in the oldest supported version oflibclang (3.5). All of these types and functions have a documentation comment which specifies the minimumlibclang version required to use the item.

To target a version oflibclang, enable a Cargo features such as one of the following:

• clang_3_5 - requireslibclang 3.5 or later
• clang_3_6 - requireslibclang 3.6 or later
• etc...
• clang_17_0 - requireslibclang 17.0 or later
• clang_18_0 - requireslibclang 18.0 or later

If you do not enable one of these features, the API provided bylibclang 3.5 will be available by default.

Note: If you are using Clang 15.0 or later, you should enable theclang_15_0 feature or a more recent version feature. Clang 15.0 introduceda breaking change to theEntityKind enum which resulted in a mismatch between the values returned bylibclang and the values forEntityKind defined by this crate in previous versions.

By default, this crate will attempt to link tolibclang dynamically. In this case, this crate depends on thelibclang shared library (libclang.so on Linux,libclang.dylib on macOS,libclang.dll on Windows). If you want to link tolibclang statically instead, enable thestatic Cargo feature. In this case, this crate depends on the LLVM and Clang static libraries. If you don't want to link tolibclang at compiletime but instead want to load it at runtime, enable theruntime Cargo feature.

These libraries can be either be installed as a part of Clang or downloadedhere.

Note: The downloads for LLVM and Clang 3.8 and later do not include thelibclang.a static library. This means you cannot link to any of these versions oflibclang statically unless you build it from source.

This crate supports finding versioned instances oflibclang.so (e.g.,libclang-3.9.so). In the case where there are multiple instances to choose from, this crate will prefer instances with higher versions. For example, the following instances oflibclang.so are listed in descending order of preference:

1. libclang-4.0.so
2. libclang-4.so
3. libclang-3.9.so
4. libclang-3.so
5. libclang.so

Note: On BSD distributions, versioned instances oflibclang.so matching the patternlibclang.so.* (e.g.,libclang.so.7.0) are also included.

Note: On Linux distributions when theruntime features is enabled, versioned instances oflibclang.so matching the patternlibclang.so.* (e.g.,libclang.so.1) are also included.

The following environment variables, if set, are used by this crate to find the required libraries and executables:

• LLVM_CONFIG_PATH(compiletime) - provides a full path to anllvm-config executable (including the executable itself [i.e.,/usr/local/bin/llvm-config-8.0])
• LIBCLANG_PATH(compiletime) - provides a path to a directory containing alibclang shared library or a full path to a specificlibclang shared library
• LIBCLANG_STATIC_PATH(compiletime) - provides a path to a directory containing LLVM and Clang static libraries
• CLANG_PATH(runtime) - provides a path to aclang executable

libclang shared libraries will be searched for in the following directories:

• the directory provided by theLIBCLANG_PATH environment variable
• thebin andlib directories in the directory provided byllvm-config --libdir
• the directories provided byLD_LIBRARY_PATH environment variable
• a list of likely directories for the target platform (e.g.,/usr/local/lib on Linux)
• macOS only: the toolchain directory in the directory provided byxcode-select --print-path

On Linux, running an executable that has been dynamically linked tolibclang may require you to add a path tolibclang.so to theLD_LIBRARY_PATH environment variable. The same is true on OS X, except theDYLD_LIBRARY_PATH environment variable is used instead.

On Windows, running an executable that has been dynamically linked tolibclang requires thatlibclang.dll can be found by the executable at runtime. Seehere for more information.

The availability ofllvm-config is not optional for static linking. Ensure that an instance of this executable can be found on your system's path or set theLLVM_CONFIG_PATH environment variable. The required LLVM and Clang static libraries will be searched for in the same way as shared libraries are searched for, except theLIBCLANG_STATIC_PATH environment variable is used in place of theLIBCLANG_PATH environment variable.

Note: Thelibcpp Cargo feature can be used to enable linking tolibc++ instead oflibstd++ when linking tolibclang statically on Linux or Haiku.

Linking tolibclang statically on *nix systems requires that thelibclang.a static library be available.
This library is usuallynot included in most distributions of LLVM and Clang (e.g.,libclang-dev on Debian-based systems).
If you need to link tolibclang statically then most likely the only consistent way to get your hands onlibclang.a is to build it yourself.

Here's an example of building the required static libraries and using them withclang-sys:

git clone git@github.com:llvm/llvm-project.gitcd llvm-projectcmake -S llvm -B build -G Ninja -DLLVM_ENABLE_PROJECTS=clang -DLIBCLANG_BUILD_STATIC=ONninja -C buildcd ..git clone git@github.com:KyleMayes/clang-sys.gitcd clang-sysLLVM_CONFIG_PATH=../llvm-project/build/bin/llvm-config cargo test --features static

Linking tolibclang statically requires linking a large number of big static libraries.
Usingrust-lld as a linker can greatly reduce linking times.

Theclang_sys::load function is used to load alibclang shared library for use in the thread in which it is called. Theclang_sys::unload function will unload thelibclang shared library.clang_sys::load searches for alibclang shared library in the same way one is searched for when linking tolibclang dynamically at compiletime.