Emboss

一个小型宏，可以将元数据作为 ELF/Mach-O 部分嵌入到您的最终二进制文件中。

非常适合与 vergen 配合使用。

快速入门

在您的 Cargo.toml 中包含 emboss

[package]
# <snip>

[dependencies]
emboss = "0.2.0"

导入宏并使用您想要嵌入的环境变量的名称调用它

use emboss::emboss;

emboss!(CARGO_PKG_VERSION);

运行快速 cargo build 然后检查生成的二进制文件

$ strings target/debug/kana | grep CARGO_PKG_VERSION
CARGO_PKG_VERSION=0.1.0

您可以从二进制文件中自行解析这些数据，或者使用 rsps 从运行进程获取它。

注意：如果环境变量不存在，宏调用将失败。如果您觉得这很烦人，请参阅 此问题。

与 vergen 一起使用

此软件包为与 vergen 使用提供了许多便捷调用。

要开始，请同时在您的 Cargo.toml 中包含 vergen 和 emboss

[package]
# <snip>
build = "build.rs"

[build-dependencies]
vergen = "5.1.5"

[dependencies]
emboss = "0.2.0"

设置您的 build.rs 以利用 vergen

use vergen::{Config, vergen};

fn main() -> Result<(), ()> {
    let mut config = Config::default();

    vergen(config).unwrap();

    Ok(())
}

最后，导入并调用 emboss

use emboss::emboss;

// Includes every rustc related env var provided by vergen
emboss!(group=rustc);

如果一切顺利，构建后，您应该在最终二进制文件中看到一些 vergen 属性

$ strings target/debug/kana | grep VERGEN
VERGEN_RUSTC_CHANNEL=stable
VERGEN_RUSTC_COMMIT_DATE=2021-05-09
VERGEN_RUSTC_COMMIT_HASH=9bc8c42bb2f19e745a63f3445f1ac248fb015e53
VERGEN_RUSTC_HOST_TRIPLE=x86_64-apple-darwin
VERGEN_RUSTC_LLVM_VERSION=12.0
VERGEN_RUSTC_SEMVER=1.52.1

配置

// Emboss an env variable by name
emboss!(FOO_ENV_VAR);

// Emboss an env variable into a custom section
emboss!(BAR_ENV_VAR, "__DATA,__custom_data");

// Emboss a specific value into a custom section
emboss!(BAZ_ENV_VAR, ".zu", "Can you feel the storm? It's coming.");

// Includes `VERGEN_BUILD_*`
emboss!(group=build);

// Includes `VERGEN_GIT_*`
emboss!(group=git);

// Includes `VERGEN_RUSTC_*`
emboss!(group=rustc);

// Includes `VERGEN_CARGO_*`
emboss!(group=cargo);

// Includes `VERGEN_SYSINFO_*`
emboss!(group=sysinfo);

// Includes both the rustc and cargo groups
emboss!(group=rust);

// Includes the following environment variables:
//  VERGEN_BUILD_TIMESTAMP
//  VERGEN_BUILD_SEMVER
//  VERGEN_RUSTC_SEMVER 
//  VERGEN_CARGO_PROFILE 
//  VERGEN_CARGO_FEATURES 
// Which rsps can use to display detailed information about your binary when it runs
emboss!(group=rsps);

// An alias for the above
emboss!();

// You can also specify multiple groups at once
// This will include both `VERGEN_SYSINFO_*` and `VERGEN_GIT_*`
emboss!(groups=sysinfo,git);

读取压印数据

我们提供了一个简单的辅助函数，可以从给定的字节序列检索压印数据。

以下是一个使用 object 软件包的示例

fn read_binary_metadata(file: &object::File) {
  // Pull the raw data from the metadata section of the binary
  // For this example, we'll assume that the following is returned:
  //    VERGEN_RUSTC_CHANNEL=stable\0VERGEN_RUSTC_COMMIT_DATE=2021-05-09\0
  let section = file.section_by_name(emboss::DEFAULT_SECTION_NAME).expect("metadata should exist");
  let data = section.data().expect("data should be available");

  let metadata = emboss::extract_metadata(data.as_bytes()).expect("should be able to parse metadata");

  let value = metadata.get("VERGEN_RUSTC_CHANNEL").expect("VERGEN_RUSTC_CHANNEL should be present");
  assert_eq!(value, "stable");

  let value = metadata.get("VERGEN_RUSTC_COMMIT_DATE").expect("VERGEN_RUSTC_COMMIT_DATE should be present");
  assert_eq!(value, "2021-05-09");
}

许可证

许可如下之一

• Apache 许可证，版本 2.0 (LICENSE-APACHE 或 https://apache.ac.cn/licenses/LICENSE-2.0)
• MIT 许可证 (LICENSE-MIT 或 http://opensource.org/licenses/MIT)

任选其一。

贡献

除非您明确说明，否则任何有意提交以包含在您的工作中的贡献，根据 Apache-2.0 许可证定义，将双重许可如上，不附加任何额外条款或条件。