clang-sys

Rust 对 libclang 的绑定。

如果您对这些绑定的 Rust 风格包装库感兴趣，请参阅 clang-rs。

在 Apache License 2.0 许可下发布。

文档

请注意，此 crate 在 https://docs.rs 上的文档假定使用了 runtime Cargo 功能以及 libclang 的最新支持版本（例如，clang_16_0）的 Cargo 功能，这些功能默认情况下均未启用。

由于使用了 runtime Cargo 功能，此文档将包含一些用于在运行时管理动态加载的 libclang 实例的类型和函数。

由于使用了 libclang 的最新支持版本的 Cargo 功能，此文档将包含在 libclang 最老支持版本（3.5）中不可用的常量和函数。所有这些类型和函数都有一个文档注释，该注释指定了使用该项所需的最低 libclang 版本。

支持版本

要针对 libclang 的某个版本进行操作，启用以下 Cargo 功能之一

• clang_3_5 - 需要 libclang 3.5 或更高版本
• clang_3_6 - 需要 libclang 3.6 或更高版本
• 等等...
• clang_17_0 - 需要 libclang 17.0 或更高版本
• clang_18_0 - 需要 libclang 18.0 或更高版本

如果您没有启用这些功能之一，默认情况下将提供 libclang 3.5 的 API。

注意：如果您正在使用Clang 15.0或更高版本，应启用clang_15_0功能或更新的版本功能。Clang 15.0引入了对EntityKind枚举的破坏性更改，导致libclang返回的值与该crate在先前版本中定义的EntityKind值不匹配。

依赖项

默认情况下，此crate将尝试动态链接到libclang。在这种情况下，此crate依赖于libclang共享库（Linux上的libclang.so，macOS上的libclang.dylib，Windows上的libclang.dll）。如果您想静态链接到libclang，请启用static Cargo功能。在这种情况下，此crate依赖于LLVM和Clang静态库。如果您不想在编译时链接到libclang，而是希望在运行时加载它，请启用runtime Cargo功能。

这些库可以作为Clang的一部分安装，或者从这里下载。

注意：LLVM和Clang 3.8及以后版本的下载不包括libclang.a静态库。这意味着除非您从源代码构建，否则您不能静态链接到这些版本的libclang。

版本依赖项

此crate支持查找libclang.so的版本实例（例如，libclang-3.9.so）。在存在多个实例可供选择的情况下，此crate将优先选择更高版本的实例。例如，以下libclang.so实例按优先级降序列出：

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

注意：在BSD发行版上，与模式libclang.so.*（例如，libclang.so.7.0）匹配的libclang.so版本实例也包括在内。

注意：在Linux发行版上，当启用了runtime功能时，与模式libclang.so.*（例如，libclang.so.1）匹配的libclang.so版本实例也包括在内。

环境变量

以下环境变量，如果已设置，则由此crate用于查找所需的库和可执行文件：

• LLVM_CONFIG_PATH （编译时） - 提供到llvm-config可执行文件的完整路径（包括可执行文件本身[即，/usr/local/bin/llvm-config-8.0])
• LIBCLANG_PATH （编译时） - 提供包含libclang共享库的目录路径或特定libclang共享库的完整路径
• LIBCLANG_STATIC_PATH （编译时） - 提供包含LLVM和Clang静态库的目录路径
• CLANG_PATH (运行时) - 提供了一个指向 clang 可执行文件的路径

链接

动态

libclang 共享库将在以下目录中搜索：

• 由环境变量 LIBCLANG_PATH 提供的目录
• bin 和 lib 目录，由 llvm-config --libdir 提供的目录
• 由环境变量 LD_LIBRARY_PATH 提供的目录
• 目标平台可能的目录列表（例如，Linux上的 /usr/local/lib）
• 仅限 macOS: 由 xcode-select --print-path 提供的目录中的工具链目录

在 Linux 上，运行动态链接到 libclang 的可执行文件可能需要您将 libclang.so 的路径添加到环境变量 LD_LIBRARY_PATH。在 OS X 上也是如此，但使用的是环境变量 DYLD_LIBRARY_PATH 而不是 LD_LIBRARY_PATH。

在 Windows 上，运行动态链接到 libclang 的可执行文件需要该可执行文件在运行时能够找到 libclang.dll。更多信息请参阅这里。

静态

对于静态链接，llvm-config 的可用性是必需的。确保在系统路径中可以找到此可执行文件的实例，或者设置环境变量 LLVM_CONFIG_PATH。所需的 LLVM 和 Clang 静态库将按与共享库搜索相同的方式进行搜索，只是使用环境变量 LIBCLANG_STATIC_PATH 而不是 LIBCLANG_PATH。

注意：可以使用 libcpp Cargo 功能来启用在 Linux 或 Haiku 上静态链接到 libc++ 而不是 libstd++。

静态库可用性

在 *nix 系统上静态链接到 libclang 需要提供 libclang.a 静态库。
这个库通常 不 包含在大多数 LLVM 和 Clang 的发行版中（例如，基于 Debian 的系统上的 libclang-dev）。
如果您需要静态链接到 libclang，那么获取 libclang.a 的唯一一致方法可能是自己构建它。

以下是构建所需的静态库并将其与 clang-sys 一起使用的示例

git clone [email protected]:llvm/llvm-project.git
cd llvm-project

cmake -S llvm -B build -G Ninja -DLLVM_ENABLE_PROJECTS=clang -DLIBCLANG_BUILD_STATIC=ON
ninja -C build

cd ..
git clone [email protected]:KyleMayes/clang-sys.git
cd clang-sys

LLVM_CONFIG_PATH=../llvm-project/build/bin/llvm-config cargo test --features static

静态链接到 libclang 需要链接大量的大型静态库。
使用rust-lld 作为链接器可以大大减少链接时间。

运行时

《clang_sys::load》函数用于在调用它的线程中加载一个用于libclang的共享库。而《clang_sys::unload》函数则用于卸载libclang共享库。《clang_sys::load》函数在编译时动态链接到libclang的方式相同，搜索一个libclang共享库。