Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Emboss
Macros to embed metadata as an ELF/Mach-O section in your final binary.
Pairs quite nicely with vergen.
Quickstart
Include emboss
in your Cargo.toml
:
[]
# <snip>
[]
= "0.5.1"
Import the emboss macro and call it with the key and value you want to embed:
use emboss;
emboss!;
Run a quick cargo build
and then examine the resulting binary:
|
my-custom-value=1
You can also parse this yourself from the binary or use rsps to fetch it from a running process.
Detailed Usage
Emboss Many
You can emboss multiple key value pairs at once using emboss_many
:
use emboss_many;
// The `items` property takes an array of key-value structs
emboss_many!;
Emboss From Environment Variables
If you need to pull the value of a environment variable for the embossing, there is emboss_env
:
use emboss_env;
// `env_var` will be the environment variable to evaluate at compile time
// `key` will be the key in the embossing, same as it is in the normal emboss macro
// If you omit `key`, it'll reuse the env var as the `key`
emboss_env!;
If the environment variable is not present at compile time, the macro will fail. You can change this behavior with the fallback
property:
use emboss_env;
// The `Fail` variant is the default behavior, blowing up when the `env_var` is missing
emboss_env!;
// The `Empty` variant will use an empty value when the `env_var` is missing
emboss_env!;
// The `Value` variant will use a specific, user-specified value when the `env_var` is missing
emboss_env!;
Emboss Many From Environment Variables
Similar to emboss_many
, but for values pulled from environment variables. You can use all the same properties present in emboss_env
:
use emboss_envs;
// The `env_vars` property takes an array of environment variable spec structs
emboss_envs!;
Exports and Enum Variants
All emboss macros support the export_name
parameter, which creates a module with a public API for accessing embossed data:
use emboss;
emboss!;
// Later in your code:
let = EMBOSSED.get_by_key.unwrap;
println!;
You can also customize enum variant names for better ergonomics:
use emboss_many;
emboss_many!;
// Access via enum variants
let = EMBOSSED.get_by_kind;
let = EMBOSSED.get_by_kind;
Extended Arguments
All emboss macros support the following properties:
stored_in
: The name of the section to store embossed data. Defaults to.emboss.meta
.
On macOS, an additional segment
parameter allows you to customize the segment that the section is placed in:
emboss!;
By default, the segment will be __DATA
.
Reading Embossed Data
We provide helper functions to retrieve embossed data from a given sequence of bytes.
Here is an example using the object crate:
use extract;
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
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.