构建脚本

一些包需要编译第三方非 Rust 代码，例如 C 库。其他包需要链接到 C 库，这些库可以位于系统上，也可能需要从源代码构建。还有一些包需要在构建之前使用代码生成等功能（例如解析器生成器）。

Cargo 的目标不是取代那些针对这些任务进行了良好优化的工具，而是通过自定义构建脚本与它们集成。在包的根目录中放置一个名为 build.rs 的文件将导致 Cargo 在构建包之前编译并执行该脚本。

// Example custom build script.
fn main() {
    // Tell Cargo that if the given file changes, to rerun this build script.
    println!("cargo::rerun-if-changed=src/hello.c");
    // Use the `cc` crate to build a C file and statically link it.
    cc::Build::new()
        .file("src/hello.c")
        .compile("hello");
}

构建脚本的一些用例示例：

  • 构建捆绑的 C 库。
  • 在主机系统上查找 C 库。
  • 从规范生成 Rust 模块。
  • 执行 crate 所需的任何特定于平台的配置。

以下部分描述了构建脚本的工作原理，示例章节展示了如何编写脚本的各种示例。

注意：package.build 清单键可用于更改构建脚本的名称，或完全禁用它。

构建脚本的生命周期

在构建包之前，Cargo 会将构建脚本编译成可执行文件（如果尚未构建）。然后它将运行该脚本，该脚本可以执行任意数量的任务。脚本可以通过向 stdout 打印以 cargo:: 为前缀的特殊格式命令与 Cargo 进行通信。

如果构建脚本的任何源文件或依赖项发生更改，则将重新构建该脚本。

默认情况下，如果包中的任何文件发生更改，Cargo 将重新运行构建脚本。通常最好使用 rerun-if 命令（在下面的更改检测部分中描述）来缩小触发构建脚本再次运行的范围。

构建脚本成功完成执行后，将编译包的其余部分。如果出现错误，脚本应以非零退出代码退出以停止构建，在这种情况下，构建脚本的输出将显示在终端上。

构建脚本的输入

运行构建脚本时，构建脚本有许多输入，所有输入都以环境变量的形式传入。

除了环境变量之外，构建脚本的当前目录是构建脚本包的源目录。

构建脚本的输出

构建脚本可以将任何输出文件或中间工件保存在OUT_DIR 环境变量指定的目录中。脚本不应修改该目录之外的任何文件。

构建脚本通过打印到 stdout 与 Cargo 进行通信。Cargo 会将以 cargo:: 开头的每一行解释为一条指令，该指令将影响包的编译。所有其他行都将被忽略。

**注意：**旧的调用前缀 cargo:（只有一个冒号）已弃用，并且不会获得任何新功能。要进行迁移，请使用两个冒号前缀 cargo::，该前缀已在 Rust 1.77 中添加。如果您使用 cargo:KEY=VALUE 来表示任意的链接清单键值对，则建议切换到 cargo::metadata=KEY=VALUE。仅当需要支持 Rust 1.77 之前的版本时，才坚持使用 cargo:。

构建脚本打印的 cargo:: 指令的顺序*可能*会影响 cargo 传递给 rustc 的参数顺序。反过来，传递给 rustc 的参数顺序可能会影响传递给链接器的参数顺序。因此，您需要注意构建脚本指令的顺序。例如，如果对象 foo 需要链接到库 bar，您可能需要确保库 bar 的 cargo::rustc-link-lib 指令出现在链接对象 foo 的指令*之后*。

在正常编译期间，脚本的输出对终端隐藏。如果您希望直接在终端中查看输出，请使用 -vv 标志以“非常详细”模式调用 Cargo。这仅在运行构建脚本时发生。如果 Cargo 确定没有任何更改，它将不会重新运行脚本，有关详细信息，请参阅下面的更改检测。

构建脚本打印到 stdout 的所有行都写入到类似 target/debug/build/<pkg>/output 的文件中（确切位置可能取决于您的配置）。stderr 输出也保存在同一目录中。

以下是 Cargo 识别的指令摘要，每个指令都在下面详细介绍。

rustc-link-arg 指令告诉 Cargo 将 -C link-arg=FLAG 选项 传递给编译器，但仅在构建受支持的目标（基准测试、二进制文件、cdylib 包、示例和测试）时才这样做。其用法高度依赖于平台。它对于设置共享库版本或链接器脚本很有用。

rustc-link-arg-bin 指令告诉 Cargo 将 -C link-arg=FLAG 选项 传递给编译器，但仅在构建名为 BIN 的二进制目标时才这样做。其用法高度依赖于平台。它对于设置链接器脚本或其他链接器选项很有用。

rustc-link-arg-bins 指令告诉 Cargo 将 -C link-arg=FLAG 选项 传递给编译器，但仅在构建二进制目标时才这样做。其用法高度依赖于平台。它对于设置链接器脚本或其他链接器选项很有用。

rustc-link-lib 指令告诉 Cargo 使用编译器的 -l 标志 链接给定的库。这通常用于使用 FFI 链接原生库。

LIB 字符串直接传递给 rustc，因此它支持 -l 支持的任何语法。

目前，LIB 支持的完整语法为 [KIND[:MODIFIERS]=]NAME[:RENAME]。

-l 标志仅传递给包的库目标，除非没有库目标，在这种情况下，它将传递给所有目标。这样做是因为所有其他目标都隐式依赖于库目标，并且给定的要链接的库应该只包含一次。这意味着，如果一个包同时具有库目标和二进制目标，则该*库*可以访问给定库中的符号，而二进制文件应该通过库目标的公共 API 访问它们。

可选的 KIND 可以是 dylib、static 或 framework。有关更多详细信息，请参阅 rustc 书籍。

rustc-link-arg-tests 指令告诉 Cargo 将 -C link-arg=FLAG 选项 传递给编译器，但仅在构建测试目标时才这样做。

rustc-link-arg-examples 指令告诉 Cargo 将 -C link-arg=FLAG 选项 传递给编译器，但仅在构建示例目标时才这样做。

rustc-link-arg-benches 指令告诉 Cargo 将 -C link-arg=FLAG 选项 传递给编译器，但仅在构建基准测试目标时才这样做。

rustc-link-search 指令告诉 Cargo 将 -L 标志 传递给编译器，以将目录添加到库搜索路径。

可选的 KIND 可以是 dependency、crate、native、framework 或 all。有关更多详细信息，请参阅 rustc 书籍。

如果这些路径位于 OUT_DIR 中，则它们也会被添加到 动态库搜索路径环境变量 中。不鼓励依赖于此行为，因为这会使生成的二进制文件难以使用。通常，最好避免在构建脚本中创建动态库（使用现有的系统库是可以的）。

cargo::rustc-flags=FLAGS

rustc-flags 指令告诉 Cargo 将给定的空格分隔的标志传递给编译器。这仅允许 -l 和 -L 标志，并且等效于使用 rustc-link-lib 和 rustc-link-search。

cargo::rustc-cfg=KEY[="VALUE"]

rustc-cfg 指令告诉 Cargo 将给定的值传递给编译器的 --cfg 标志。这可以用于编译时检测要启用的功能以进行 条件编译。

请注意，这*不会*影响 Cargo 的依赖项解析。这不能用于启用可选依赖项或启用其他 Cargo 功能。

请注意，Cargo 功能 使用 feature="foo" 的形式。使用此标志传递的 cfg 值不限于该形式，并且可以仅提供单个标识符或任何任意的键/值对。例如，发出 cargo::rustc-cfg=abc 将允许代码使用 #[cfg(abc)]（注意缺少 feature=）。或者，可以使用带有 = 符号的任意键/值对，例如 cargo::rustc-cfg=my_component="foo"。键应该是 Rust 标识符，值应该是字符串。

cargo::rustc-env=VAR=VALUE

rustc-env 指令告诉 Cargo 在编译包时设置给定的环境变量。然后，编译后的包中的 env! 宏 可以检索该值。这对于在包的代码中嵌入其他元数据很有用，例如 git HEAD 的哈希值或持续集成服务器的唯一标识符。

另请参阅 Cargo 自动包含的环境变量。

**注意**：在使用 cargo run 或 cargo test 运行可执行文件时，也会设置这些环境变量。但是，不鼓励这种用法，因为它将可执行文件绑定到 Cargo 的执行环境。通常，只应在编译时使用 env! 宏检查这些环境变量。

rustc-cdylib-link-arg 指令告诉 Cargo 将 -C link-arg=FLAG 选项 传递给编译器，但仅在构建 cdylib 库目标时才这样做。其用法高度依赖于平台。它对于设置共享库版本或运行时路径很有用。

cargo::warning=MESSAGE

warning 指令告诉 Cargo 在构建脚本完成运行后显示警告。警告仅针对 path 依赖项（即您在本地处理的依赖项）显示，因此，例如，默认情况下不会发出 crates.io 包中打印的警告。可以使用 -vv“非常详细”标志让 Cargo 显示所有包的警告。

构建依赖项

构建脚本也允许依赖于其他基于 Cargo 的包。依赖项通过清单的 build-dependencies 部分声明。

[build-dependencies]
cc = "1.0.46"

构建脚本*不能*访问 dependencies 或 dev-dependencies 部分中列出的依赖项（它们尚未构建！）。此外，除非在 [dependencies] 表中也明确添加，否则包本身无法使用构建依赖项。

建议您仔细考虑添加的每个依赖项，权衡其对编译时间、许可、维护等的影响。如果依赖项在构建依赖项和普通依赖项之间共享，Cargo 将尝试重用它。但是，这并不总是可行的，例如在交叉编译时，因此请考虑对编译时间的影响。

更改检测

在重建包时，Cargo 不一定知道是否需要再次运行构建脚本。默认情况下，如果包中的任何文件发生更改（或由 exclude 和 include 字段 控制的文件列表发生更改），它会采用始终重新运行构建脚本的保守方法。在大多数情况下，这不是一个好的选择，因此建议每个构建脚本至少发出一个 rerun-if 指令（如下所述）。如果发出这些指令，则 Cargo 仅在给定的值发生更改时才会重新运行脚本。如果 Cargo 正在重新运行您自己的包或依赖项的构建脚本，并且您不知道原因，请参阅常见问题解答中的 “为什么 Cargo 正在重建我的代码？”。

cargo::rerun-if-changed=PATH

rerun-if-changed 指令告诉 Cargo 如果给定路径处的文件已更改，则重新运行构建脚本。目前，Cargo 仅使用文件系统上次修改时间“mtime”时间戳来确定文件是否已更改。它与上次运行构建脚本时的内部缓存时间戳进行比较。

如果路径指向目录，它将扫描整个目录以查找任何修改。

如果构建脚本本身在任何情况下都不需要重新运行，则发出 cargo::rerun-if-changed=build.rs 是一种防止其重新运行的简单方法（否则，如果没有发出 rerun-if 指令，则默认情况下会扫描整个包目录以查找更改）。Cargo 会自动处理脚本本身是否需要重新编译，当然，脚本在重新编译后会重新运行。否则，指定 build.rs 是多余且不必要的。

cargo::rerun-if-env-changed=NAME

rerun-if-env-changed 指令告诉 Cargo 如果给定名称的环境变量的值已更改，则重新运行构建脚本。

请注意，这里的环境变量适用于 CC 等全局环境变量，不能将其用于 Cargo 为构建脚本设置 的 TARGET 等环境变量。正在使用的环境变量是 cargo 调用接收到的环境变量，而不是构建脚本的可执行文件接收到的环境变量。

可以在 Cargo.toml 清单中设置 package.links 键，以声明包与给定的原生库链接。此清单键的目的是让 Cargo 了解包具有的原生依赖项集，以及提供在包构建脚本之间传递元数据的原则性系统。

[package]
# ...
links = "foo"

此清单声明包链接到 libfoo 原生库。使用 links 键时，包必须具有构建脚本，并且构建脚本应使用 rustc-link-lib 指令 来链接库。

首先，Cargo 要求每个 links 值最多有一个包。换句话说，禁止两个包链接到同一个原生库。这有助于防止包之间的符号重复。但是请注意，有一些 约定 可以缓解这种情况。

构建脚本可以生成任意键值对形式的元数据集。此元数据使用 cargo::metadata=KEY=VALUE 指令设置。

元数据会被传递给**依赖**包的构建脚本。例如，如果包 bar 依赖于 foo，并且 foo 在其构建脚本元数据中生成了 key=value，那么 bar 的构建脚本将具有环境变量 DEP_FOO_KEY=value。有关如何使用此功能的示例，请参阅“使用另一个 sys 包”。

请注意，元数据仅传递给直接依赖项，而不传递给传递依赖项。

*-sys 包

一些链接到系统库的 Cargo 包的命名约定是在名称后添加 -sys 后缀。任何名为 foo-sys 的包都应该提供两个主要功能：

  • 库包应该链接到原生库 libfoo。这通常会在从源代码构建之前先在当前系统中探测 libfoo。
  • 库包应该提供 libfoo 中类型和函数的**声明**，但**不**提供更高级别的抽象。

*-sys 包集为链接到原生库提供了一组通用的依赖项。拥有这种与原生库相关的包的约定有很多好处：

  • 对 foo-sys 的通用依赖项减轻了每个 links 值只能有一个包的规则。
  • 其他 -sys 包可以利用 DEP_NAME_KEY=value 环境变量更好地与其他包集成。请参阅“使用另一个 sys 包”示例。
  • 通用依赖项允许集中逻辑来发现 libfoo 本身（或从源代码构建它）。
  • 这些依赖项很容易覆盖。

通常会有一个没有 -sys 后缀的配套包，它在 sys 包之上提供安全、高级的抽象。例如，git2 包为libgit2-sys 包提供了一个高级接口。

覆盖构建脚本

如果清单包含 links 键，则 Cargo 支持使用自定义库覆盖指定的构建脚本。此功能的目的是完全阻止运行相关构建脚本，而是提前提供元数据。

要覆盖构建脚本，请在任何可接受的config.toml文件中放置以下配置。

[target.x86_64-unknown-linux-gnu.foo]
rustc-link-lib = ["foo"]
rustc-link-search = ["/path/to/foo"]
rustc-flags = "-L /some/path"
rustc-cfg = ['key="value"']
rustc-env = {key = "value"}
rustc-cdylib-link-arg = ["…"]
metadata_key1 = "value"
metadata_key2 = "value"

使用此配置，如果包声明它链接到 foo，则**不会**编译或运行构建脚本，而是使用指定的元数据。

不应使用 warning、rerun-if-changed 和 rerun-if-env-changed 键，它们将被忽略。

作业服务器

Cargo 和 rustc 使用为 GNU make 开发的作业服务器协议来协调进程间的并发性。它本质上是一个控制并发运行作业数量的信号量。可以使用 --jobs 标志设置并发度，该标志默认为逻辑 CPU 的数量。

每个构建脚本从 Cargo 继承一个作业槽，并且应该努力在运行时只使用一个 CPU。如果脚本希望并行使用更多 CPU，则应使用jobserver 包与 Cargo 进行协调。

例如，cc 包可以启用可选的 parallel 功能，该功能将使用作业服务器协议尝试同时构建多个 C 文件。