shadow-rs: 在您的Rust项目中存储的构建时信息（二进制、库、cdylib、dylib）。

shadow-rs 允许您在运行时访问构建过程和环境的属性，包括

• Cargo.toml 信息，如项目版本
• 依赖信息
• Git信息，如生成构建实体的提交
• 在编译过程中使用的Rust工具链版本
• 构建变体，例如 debug 或 release
• ... 更多内容！

您可以使用这个crate来编程检查二进制文件的来源和构建方式。

目前，也支持集成到 wasm。有关详细设置，请参阅链接 example_wasm。

关于缓存的说明

shadow-rs 的构建信息 在构建项目时并不总是重新构建。 shadow-rs 向Cargo输出几个提示，以便在需要时强制重新构建，但这并不总是有效。您可以通过在构建前运行 cargo clean 来强制更新构建信息，或者使用CI/CD管道工具。更多详情请参阅 https://github.com/baoyachi/shadow-rs/issues/95。

示例

• 查看 example_shadow 以了解如何使用 shadow-rs 在运行时提供构建时信息。
• 查看 example_shadow_hook 以了解如何使用自定义钩子向 shadow-rs 的输出添加额外信息。
• 查看 builtin_fn 示例 以了解 shadow-rs 提供的内置函数。

设置

1) 修改 Cargo.toml 字段

按照如下方式修改您的 Cargo.toml

[package]
build = "build.rs"

[dependencies]
shadow-rs = "{latest version}"

[build-dependencies]
shadow-rs = "{latest version}"

关于 build = "build.rs"，这是一个可选的添加项，默认情况下，构建指向 build.rs 文件。建议这样使用。但是，如果您的构建脚本文件不是 build.rs，请手动指定它。例如：build = "gen.rs"。

2) 创建 build.rs 文件

现在在您的项目根目录中（与 Cargo.toml 相同的目录）添加一个文件 build.rs

fn main() -> shadow_rs::SdResult<()> {
    shadow_rs::new()
}

如果您想排除某些构建常量，可以使用 new_deny 而不是 [new]。

3) 集成 Shadow

在您的主 Rust 文件中（通常是 main.rs 或 lib.rs），添加以下内容

use shadow_rs::shadow;

shadow!(build);

shadow! 宏使用给定的标识符创建一个具有该名称的模块。

4) 使用 Shadow 常量

现在您可以使用使用 shadow! 定义的模块来访问构建时信息。

fn main() {
    println!("debug:{}", shadow_rs::is_debug()); // check if this is a debug build. e.g 'true/false'
    println!("branch:{}", shadow_rs::branch()); // get current project branch. e.g 'master/develop'
    println!("tag:{}", shadow_rs::tag()); // get current project tag. e.g 'v1.3.5'
    println!("git_clean:{}", shadow_rs::git_clean()); // get current project clean. e.g 'true/false'
    println!("git_status_file:{}", shadow_rs::git_status_file()); // get current project statue file. e.g '  * examples/builtin_fn.rs (dirty)'

    println!("{}", build::VERSION); //print version const
    println!("{}", build::CLAP_LONG_VERSION); //print CLAP_LONG_VERSION const
    println!("{}", build::BRANCH); //master
    println!("{}", build::SHORT_COMMIT); //8405e28e
    println!("{}", build::COMMIT_HASH); //8405e28e64080a09525a6cf1b07c22fcaf71a5c5
    println!("{}", build::COMMIT_DATE); //2021-08-04 12:34:03 +00:00
    println!("{}", build::COMMIT_AUTHOR); //baoyachi
    println!("{}", build::COMMIT_EMAIL); //[email protected]

    println!("{}", build::BUILD_OS); //macos-x86_64
    println!("{}", build::RUST_VERSION); //rustc 1.45.0 (5c1f21c3b 2020-07-13)
    println!("{}", build::RUST_CHANNEL); //stable-x86_64-apple-darwin (default)
    println!("{}", build::CARGO_VERSION); //cargo 1.45.0 (744bd1fbb 2020-06-15)
    println!("{}", build::PKG_VERSION); //0.3.13
    println!("{}", build::CARGO_TREE); //like command:cargo tree
    println!("{}", build::CARGO_MANIFEST_DIR); // /User/baoyachi/shadow-rs/ |

    println!("{}", build::PROJECT_NAME); //shadow-rs
    println!("{}", build::BUILD_TIME); //2020-08-16 14:50:25
    println!("{}", build::BUILD_RUST_CHANNEL); //debug
    println!("{}", build::GIT_CLEAN); //false
    println!("{}", build::GIT_STATUS_FILE); //* src/lib.rs (dirty)
}

可重现性

此工具包括二进制文件中的当前时间，这通常会使其不可重现。但是，它尊重 SOURCE_DATE_EPOCH 变量 - 如果设置为Unix时间戳，则将覆盖构建时间。

Clap

您还可以使用 shadow-rs 向命令行界面crate（如 clap）提供信息。一个示例可以在 example_shadow 中找到。

常量和函数列表

函数

常量

如果您有任何疑问，请创建一个问题，以便我们可以在文档可能不明确的地方进行改进。

使用 shadow-rs 的人

如果您正在使用 shadow-rs，请告诉我！或者，可以考虑在这里留下笔记：[Shadow 用户收集](https://github.com/baoyachi/shadow-rs/issues/19)。

nushell

starship

exocore exocore

bagua-core

inclavare-containers