Crate cargo_emit

Source
Expand description

Talk to Cargo easily at build time, brought to you by Nikolai Vazquez.

This library provides:

  • Convenience macros for communicating with Cargo during the build.rs phrase. Cargo listens to certain build script outputs that dictate how it should behave.

  • An accessible location for seeing what script build outputs are available to emit.

  • Protection against typos that can be made when printing these formatted outputs directly yourself. Mistyping macro names will result in a compile failure.

§Usage

This crate is available on crates.io and can be used by adding the following to your project’s Cargo.toml:

[build-dependencies]
cargo-emit = "0.1"

and something like this to your build.rs:

if should_warn {
    cargo_emit::warning!("(C-3PO voice) We're doomed");
}

Note: This library is meant to be used with Rust 2018 edition, so that cargo_emit:: can be used to prefix macro calls.

§Compatibility

This crate is compatible with Rust 1.31+ in order to use the $crate::macro! feature introduced in Rust 2018.

§Examples

Very thorough examples are provided in the docs for each individual macro.

This project is made freely available (as in free beer), but unfortunately not all beer is free! So, if you would like to buy me a beer (or coffee or more), then consider supporting my work that’s benefited your project and thousands of others.

Become a Patron! Buy me a coffee

Macros§

  • pair
    Emits a $key/$value pair to Cargo based on build script outputs.
  • rerun_if_changed
    Tells Cargo to run again if the file or directory at $path changes.
  • rerun_if_env_changed
    Tells Cargo to run again if the file or directory at $key changes.
  • rustc_cdylib_link_arg
    Tells Cargo to pass -C link-arg=$flag to the compiler.
  • rustc_cfg
    Tells Cargo to enable a $feature.
  • rustc_env
    Tells Cargo to assign $key for the environment variable for $key.
  • rustc_flags
    Tells Cargo to pass $flags to the compiler.
  • rustc_link_arg
    Tells Cargo to pass the -C link-arg=FLAG option to the compiler, but only when building supported targets (benchmarks, binaries, cdylib crates, examples, and tests). Its usage is highly platform specific. It is useful to set the shared library version or linker script.
  • rustc_link_arg_bin
    Tells Cargo to pass the -C link-arg=$flag option to the compiler, but only when building the binary target with name $bin. Its usage is highly platform specific. It is useful to set a linker script or other linker options.
  • rustc_link_arg_bins
    Tells Cargo to pass the -C link-arg=$flag option to the compiler, but only when building a binary target. Its usage is highly platform specific. It is useful to set a linker script or other linker options.
  • rustc_link_lib
    Tells Cargo to pass $lib to the compiler as a -l flag.
  • rustc_link_search
    Tells Cargo to pass $path to the compiler as a -L flag.
  • warning
    Tells Cargo to print the formatted warning message.