Rust对LLVM的C API的绑定。

使用方法

[dependencies]
llvm-sys = "180"

必须有一个兼容版本的LLVM可用。默认情况下，llvm-sys将查找llvm-config在PATH上，以找到系统范围内的LLVM副本并使用它（如果它是兼容版本）。可以通过环境变量指定在您的系统上查找LLVM的自定义选项。有关更多信息，请参阅LLVM兼容性。

文档

请参阅此存储库中的examples目录中的API示例。还有一些其他项目使用这些绑定，可能是有用的信息

• 安全的、"Rusty"的LLVM使用API
  • Inkwell
  • llvm-ir
• Tari的merthc
• Wilfred的BF编译器
• Jay Phelps撰写了关于构建针对WebAssembly的最小编译器的文章
  • Lyle使用clang扩展了arm64
• Lyle使用LALRPOP编写了小型PoC编译器Calculon

大多数接口在这些绑定中未进行文档说明。有关更多信息，请参阅LLVM文档，特别是生成的API文档。

如果您有自己的项目使用这些绑定，并且认为值得在此提及，请告知我。

Cargo功能

此crate提供了一些可能对特定用途很重要的功能标志。这些主要仅在构建时有用；如果您在构建依赖于llvm-sys的项目时遇到问题，启用一个或多个选项可能很有用；例如

cargo build --features=llvm-sys/prefer-dynamic

大多数依赖于llvm-sys的crate不应自动启用这些功能，因为任何给定选项的适用性通常取决于编译库的系统配置。

• 动态/静态链接偏好 prefer-dynamic，force-dynamic，prefer-static，force-static。只能指定其中一种，表示LLVM应该如何链接。如果没有启用任何一种，则默认为 force-static（与不支持动态链接的较旧版本的 llvm-sys 的行为相匹配）。

  动态链接时，crate 将链接到 LLVM 共享库（Windows上的.dll，Linux和类似系统上的.so等），该库必须在运行时可用；静态链接则使用静态库归档（Windows上的.lib或大多数类Unix系统上的.a），它包括最终二进制文件中的所有库代码（增加文件大小，但消除了运行程序对其他文件的依赖）。

  如果启用了 prefer- 选项，crate 将尝试使用指定的链接类型（静态或动态），但如果第一种类型不可用，则回退到另一种。设置 force- 选项将只尝试执行指定的链接类型，否则失败。

• strict-versioning：如果找不到与当前crate版本完全匹配的LLVM版本，则构建将失败。如果启用，则将crate版本150.1.0链接到LLVM 16.0（例如）将失败，而通常这是允许的。

  如果已知某些LLVM版本之间存在不兼容性，导致构建失败而不是可能在运行时引起错误，则这可能很有用。

• disable-alltargets-init：禁用构建为所有支持的目标初始化LLVM组件的函数。这些函数需要从C编译，因此如果它们不需要，则关闭它们可以在没有可用的C编译器的情况下允许构建继续。

• no-llvm-linking：防止 llvm-sys 指示编译器链接到任何LLVM库。如果其他crate以某种不同方式链接LLVM（防止冲突），则这可能很有用，但意味着其他crate必须确保满足 llvm-sys 的库需求。

构建需求

llvm-sys 需要一个与要构建的LLVM版本相对应的 llvm-config 的副本：llvm-config 允许它探测需要链接哪些库以及需要哪些编译器选项。

LLVM的二进制发行版（包括官方发布包）通常 不包括 llvm-config 的副本，因此它们不适用于使用 llvm-sys 构建程序。已知例外（包含 llvm-config 的副本）包括

• apt.llvm.org 的官方Debian/Ubuntu软件包
• Arch Linux的 llvm 软件包

如果您的平台没有提供合适的二进制软件包，通常从源代码编译是最好的选择。有关详细信息，请参阅本文件中的编译LLVM。

对于给定的项目，可能很难甚至不可能在全局范围内提供兼容的LLVM版本系统（考虑使用两个库的程序，这些库内部使用不同的LLVM版本！），因此可以设置环境变量以帮助构建脚本来找到库的副本。如果您无法提供全局范围内的LLVM版本但可以自己编译它，这也很有帮助。

LLVM_SYS_<version>_PREFIX 用于指定编译和安装的库的安装前缀，其中 <version> 是 llvm-sys 的主版本号（例如，LLVM_SYS_37_PREFIX）。LLVM-sys 构建脚本将除了在 $PATH 中寻找副本外，还会在 <PREFIX>/bin/ 目录中查找 llvm-config 二进制文件，并验证由 llvm-config 报告的 LLVM 版本是否与当前crate版本兼容。

LLVM 兼容性

由于 LLVM C API 稳定性保证 相对较弱，此 crate 强制使用与构建时相同的 LLVM 版本。crate 版本通过将 LLVM 版本视为实数并乘以 10（忽略任何小数部分）来构建。因此，llvm-sys 版本 37 与 LLVM 3.7.x 兼容，而 llvm-sys 41 将与 LLVM 4.1.x 兼容。

构建脚本不会严格强制此兼容性矩阵，允许针对至少与 crate 目标版本一样新的任何版本的 LLVM 进行编译。这在大多数情况下是安全的，因为 LLVM C API 旨在在发布之间保持二进制兼容性，除了在函数弃用并最终移除的情况下。不兼容的 LLVM 版本通常会在链接时失败并显示链接时间错误，而不是导致运行时错误。已知版本会破坏二进制兼容性时，构建脚本将阻止编译。

根据您对 C API 的使用，您的程序可能需要只允许与 crate 版本完全匹配的 LLVM 版本。这可以通过设置 cargo 功能标志 strict-versioning 或通过设置环境变量 LLVM_SYS_<version>_STRICT_VERSIONING（其中 <version> 是目标 crate 版本）为任何值来实现。

llvm-sys 列出了已知与二进制不兼容的一些 LLVM 版本。如果您想试试运气，可以将 LLVM_SYS_<version>_IGNORE_BLOCKLIST 设置为 "YES"，以允许使用被列入黑名单的库版本（这可能导致令人烦恼的bug）。

此 crate 声明它链接到 llvm-<MAJOR VERSION>，而不仅仅是 llvm。这使得可以声明一个依赖于多个 llvm-sys 版本的 crate（对应于不同的 LLVM 版本），只要实际上只使用了其中一个即可。

llvm-sys-90 = { package = "llvm-sys", version = "90", optional = true }
llvm-sys-100 = { package = "llvm-sys", version = "100", optional = true }

这要求将目标 LLVM 版本（例如 llvm-10）声明为链接目标，而不是仅仅声明为 llvm，因为 Cargo 要求所有链接库都必须是唯一的，而不管实际启用了哪些。请注意，尽管 Cargo 不会阻止您同时启用多个 LLVM 版本，但这样做很可能会在链接时引发错误。

编译 LLVM

如果您需要编译 LLVM 或管理多个版本，可以使用 llvmenv 来简化这个过程。如果没有特殊需求或 LLVM 使用经验，请考虑使用它！

虽然 入门指南 是编译 LLVM 的官方指南，但本节将尝试提供创建可使用库的最小指导。如果遇到问题，请参考官方文档。

下载源代码

下载并解压所需版本的源代码。

wget https://llvm.net.cn/releases/3.9.0/llvm-3.9.0.src.tar.xz
tar xJf llvm-3.9.0.src.tar.xz

请注意，您不需要编译 Clang 或测试套件。

配置

使用 CMake 配置构建（您需要安装 CMake 的副本）。

mkdir -p llvm-3.9.0.src/build
cd llvm-3.9.0.src/build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/llvm-3.9.0

在配置时可以指定的某些有用选项（通过传递给 CMake 的 -D）

• CMAKE_INSTALL_PREFIX 设置在安装步骤（稍后）中安装所有内容的目录。在上面的示例中，它位于您的家目录下。
• CMAKE_BUILD_TYPE 指定构建模式，可以是 Debug、Release、MinSizeRel 或 RelWithDebInfo。除非您计划调试 LLVM 本身，否则 Release 或 MinSizeRel 可能是一个不错的选择。
• LLVM_ENABLE_ASSERTIONS 启用内部健全性检查，当编写和调试使用 LLVM 的程序时强烈推荐，因为它可以检测许多可能导致难以调试的崩溃的错误。

将 -G <generator> 传递给 CMake 将使其使用不同的构建系统，但默认情况下，它将选择适合您的系统的一个。如果您有 ninja，则推荐使用它，因为它速度快（使用 -G Ninja）。

编译和安装

cmake --build . --target install

完成后，这将自动调用构建系统并将二进制文件复制到配置时指定的前缀中。某些构建工具（如 Windows 上的 Visual Studio）支持同时支持所有配置，因此您还需要指定构建类型（Windows 上的默认值为 Debug），可以向此 CMake 调用添加一个选项，例如 --config MinSizeRel。

CMake 构建和安装后，您可以针对它编译 llvm-sys。

cd your/crate/path
LLVM_SYS_39_PREFIX=$HOME/llvm-3.9.0 cargo build

Windows

您必须使用与构建 LLVM 相同编译器的 Rust 版本，即 MSVC 或 MinGW。幸运的是，这样的不匹配将在编译时导致错误，因为 llvm-config 提供的选项仅支持其中一个，所以如果您使用另一个，它将导致构建失败。

交叉编译

理论上可以工作，但尚未经过测试。如果您尝试了，请告诉我们。