如何在 Rust 的 build.rs 脚本中设置 RUSTFLAGS？

2024-08-21 04:56:25

从构建脚本设置 RUSTFLAGS 环境变量的正确姿势

你是否遇到过需要在 Rust 项目的构建过程中设置 RUSTFLAGS 环境变量的情况？你是否尝试过直接在 build.rs 脚本中使用 std::env::set_var，却发现修改并没有生效？

很多开发者在初次接触 build.rs 脚本时都会遇到这个问题。我们期望通过设置 RUSTFLAGS 环境变量来影响编译器的行为，例如传递额外的编译参数或链接参数。然而，直接在 build.rs 中修改环境变量并不会影响 Cargo 的编译过程。

这是为什么呢？

深入 Cargo 的构建过程

要理解这个问题，我们需要先了解 Cargo 的构建过程。当我们执行 cargo build 命令时，Cargo 会进行一系列操作：

解析项目依赖： Cargo 会分析项目的 Cargo.toml 文件，并下载所有依赖的库。
执行 build.rs 脚本： 如果项目中存在 build.rs 脚本，Cargo 会编译并执行它。
编译 Rust 代码： Cargo 调用 Rust 编译器 (rustc) 来编译项目的源代码，以及所有依赖的库。
链接目标文件： Cargo 调用链接器将所有编译好的目标文件链接成最终的可执行文件或库文件。

关键在于，Cargo 在执行 build.rs 脚本时，会创建一个新的环境，而这个环境与 Cargo 实际编译代码时使用的环境是相互隔离的。也就是说，我们在 build.rs 中通过 std::env::set_var 设置的环境变量，只会在 build.rs 脚本自身的运行环境中生效，而不会影响到 Cargo 之后的编译过程。

Cargo 提供的解决方案

为了解决这个问题，Cargo 提供了一种特殊的机制，允许我们在 build.rs 脚本中与 Cargo 进行通信，并将信息传递给编译器。

1. `cargo:rustc-env=VAR=VALUE`

Cargo 为 build.rs 脚本提供了一种特殊的语法，可以通过打印特定的格式化字符串，将环境变量传递给 Rust 编译器。

例如，假设我们希望在编译过程中设置 RUSTFLAGS="-C link-args=-Wl,-rpath,."，以便在运行时动态链接库文件。我们可以在 build.rs 脚本中添加如下代码：

println!("cargo:rustc-env=RUSTFLAGS=-C link-args=-Wl,-rpath,.");

这段代码会在 Cargo 执行 build.rs 脚本时打印一行信息到标准输出。Cargo 会捕获这行信息，并将其解析为设置环境变量的指令。最终，Cargo 会在编译 Rust 代码时，将 RUSTFLAGS 环境变量设置为 -C link-args=-Wl,-rpath,.。

2. `cargo:rustc-flags=FLAGS`

除了 cargo:rustc-env，Cargo 还提供了另一个常用的指令：cargo:rustc-flags。这个指令允许我们直接传递编译参数或链接参数给 Rust 编译器。

例如，如果我们想要设置链接器参数 -Wl,-rpath,.，更推荐使用 cargo:rustc-flags 来传递：

println!("cargo:rustc-flags=-L ."); // 将当前目录添加到库搜索路径
println!("cargo:rustc-flags=-Wl,-rpath,."); // 设置运行时库搜索路径

这种方式更加清晰地表明了我们想要设置的是链接器参数，同时也避免了直接操作 RUSTFLAGS 可能带来的副作用。

示例分析

让我们回到最初的问题，如何在 build.rs 脚本中设置 RUSTFLAGS="-C link-args=-Wl,-rpath,."。

根据前面的介绍，正确的 build.rs 脚本应该如下所示：

fn main() {
    println!("cargo:rustc-flags=-L .");
    println!("cargo:rustc-flags=-Wl,-rpath,.");
}

这段代码通过 cargo:rustc-flags 指令将链接器参数 -L . 和 -Wl,-rpath,. 传递给 Rust 编译器，实现了在运行时动态链接库文件的目标。

总结

通过本文，我们深入探讨了在 build.rs 脚本中设置 RUSTFLAGS 环境变量的正确方法，并解释了 Cargo 构建过程中的环境隔离机制。请记住，使用 cargo:rustc-env 和 cargo:rustc-flags 是与 Cargo 交互的正确方式，可以确保你的设置被正确应用到编译过程中。

常见问题

问：为什么我的 build.rs 脚本没有被执行？

答：请确保你的 build.rs 脚本位于项目的根目录下，并且在 Cargo.toml 文件中没有被禁用。
问：我可以使用哪些其他的 cargo: 指令？

答：除了 cargo:rustc-env 和 cargo:rustc-flags，Cargo 还提供了许多其他的指令，例如 cargo:rerun-if-changed、cargo:rustc-link-search 等等。你可以在 Cargo 的官方文档中找到完整的指令列表。
问：我应该在 cargo:rustc-env 中设置哪些环境变量？

答：一般来说，你应该只在 cargo:rustc-env 中设置那些需要传递给 Rust 编译器或链接器的环境变量，例如 RUSTFLAGS、CFLAGS、LDFLAGS 等等。
问：cargo:rustc-flags 和 cargo:rustc-env=RUSTFLAGS 有什么区别？

答：cargo:rustc-flags 更推荐用于传递编译参数和链接参数，而 cargo:rustc-env=RUSTFLAGS 则用于设置 RUSTFLAGS 环境变量，可能会影响到编译器的其他行为。
问：我在哪里可以找到更多关于 build.rs 脚本的信息？

答：你可以在 Cargo 的官方文档中找到更多关于 build.rs 脚本的信息，包括详细的语法说明、示例代码以及常见问题解答。