A small macro to embed metadata as an ELF/Mach-O section in your final binary.
Pairs quite nicely with vergen.
Include emboss in your Cargo.toml:
```toml [package]
[dependencies] emboss = "0.2.0" ```
Import the macro and call it with the name of the environment variable you want to embed:
```rust use emboss::emboss;
emboss!(CARGOPKGVERSION); ```
Run a quick cargo build and then examine the resulting binary:
bash
$ strings target/debug/kana | grep CARGO_PKG_VERSION
CARGO_PKG_VERSION=0.1.0
You can either parse this yourself from the binary or use rsps to fetch it from a running process.
Note: if the environment variable isn't present, the macro invocation will fail. If this annoys you, please see this issue.
This crate has many convenience calls for use with vergen.
To get started, include both vergen and emboss in your Cargo.toml:
```toml [package]
build = "build.rs"
[build-dependencies] vergen = "5.1.5"
[dependencies] emboss = "0.2.0" ```
Set up your build.rs to utilize vergen:
```rust use vergen::{Config, vergen};
fn main() -> Result<(), ()> { let mut config = Config::default();
vergen(config).unwrap();
Ok(())
} ```
Finally, import and call emboss:
```rust use emboss::emboss;
// Includes every rustc related env var provided by vergen emboss!(group=rustc); ```
If all went well, following a build, you should see some vergen attributes in the final binary:
bash
$ 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
```rust // Emboss an env variable by name emboss!(FOOENVVAR);
// Emboss an env variable into a custom section emboss!(BARENVVAR, "DATA,custom_data");
// Emboss a specific value into a custom section emboss!(BAZENVVAR, ".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: // VERGENBUILDTIMESTAMP // VERGENBUILDSEMVER // VERGENRUSTCSEMVER // VERGENCARGOPROFILE // VERGENCARGOFEATURES // 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);
```
We provide a simple helper function to retrieve embossed data from a given sequence of bytes.
Here is an example using the object crate:
```rust fn readbinarymetadata(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: // VERGENRUSTCCHANNEL=stable\0VERGENRUSTCCOMMITDATE=2021-05-09\0 let section = file.sectionbyname(emboss::DEFAULTSECTION_NAME).expect("metadata should exist"); let data = section.data().expect("data should be available");
let metadata = emboss::extractmetadata(data.asbytes()).expect("should be able to parse metadata");
let value = metadata.get("VERGENRUSTCCHANNEL").expect("VERGENRUSTCCHANNEL should be present"); assert_eq!(value, "stable");
let value = metadata.get("VERGENRUSTCCOMMITDATE").expect("VERGENRUSTCCOMMITDATE should be present"); assert_eq!(value, "2021-05-09"); } ```
Licensed under either of
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.