cargo_emit/lib.rs
1//! <div align="center">
2//! <a href="https://github.com/nvzqz/cargo-emit">
3//! <img src="https://raw.githubusercontent.com/nvzqz/cargo-emit/assets/logo.svg?sanitize=true"
4//! alt="Cargo Emit Logo"
5//! width="300"
6//! height="300">
7//! </a>
8//! <br><br>
9//! <a href="https://crates.io/crates/cargo-emit">
10//! <img src="https://img.shields.io/crates/d/cargo-emit.svg"
11//! alt="Downloads">
12//! </a>
13//! <a href="https://travis-ci.com/nvzqz/cargo-emit">
14//! <img src="https://travis-ci.com/nvzqz/cargo-emit.svg?branch=master"
15//! alt="Build Status">
16//! </a>
17//! <img src="https://img.shields.io/badge/rustc-^1.37.0-blue.svg"
18//! alt="rustc ^1.37.0">
19//! <br><br>
20//! </div>
21//!
22//! Talk to Cargo easily at build time, brought to you by [Nikolai Vazquez].
23//!
24//! This library provides:
25//!
26//! - Convenience macros for communicating with Cargo during the [`build.rs`]
27//! phrase. Cargo listens to certain [build script outputs] that dictate how
28//! it should behave.
29//!
30//! - An accessible location for seeing what script build outputs are available
31//! to emit.
32//!
33//! - Protection against typos that can be made when printing these formatted
34//! outputs directly yourself. Mistyping macro names will result in a compile
35//! failure.
36//!
37//! # Usage
38//!
39//! This crate is available [on crates.io][crate] and can be used by adding the
40//! following to your project's [`Cargo.toml`]:
41//!
42//! ```toml
43//! [build-dependencies]
44//! cargo-emit = "0.1"
45//! ```
46//!
47//! and something like this to your [`build.rs`]:
48//!
49//! ```
50//! # let should_warn = true;
51//! if should_warn {
52//! cargo_emit::warning!("(C-3PO voice) We're doomed");
53//! }
54//! ```
55//!
56//! **Note:** This library is meant to be used with [Rust 2018 edition][2018],
57//! so that `cargo_emit::` can be used to prefix macro calls.
58//!
59//! # Compatibility
60//!
61//! This crate is compatible with Rust 1.31+ in order to use the
62//! `$crate::macro!` feature introduced in [Rust 2018][2018].
63//!
64//! # Examples
65//!
66//! Very thorough examples are provided in the docs for
67//! [each individual macro](#macros).
68//!
69//! # Donate
70//!
71//! This project is made freely available (as in free beer), but unfortunately
72//! not all beer is free! So, if you would like to buy me a beer (or coffee or
73//! *more*), then consider supporting my work that's benefited your project
74//! and thousands of others.
75//!
76//! <a href="https://www.patreon.com/nvzqz">
77//! <img src="https://c5.patreon.com/external/logo/become_a_patron_button.png" alt="Become a Patron!" height="35">
78//! </a>
79//! <a href="https://www.paypal.me/nvzqz">
80//! <img src="https://buymecoffee.intm.org/img/button-paypal-white.png" alt="Buy me a coffee" height="35">
81//! </a>
82//!
83//! [Nikolai Vazquez]: https://twitter.com/NikolaiVazquez
84//! [build script outputs]: https://doc.rust-lang.org/cargo/reference/build-scripts.html#outputs-of-the-build-script
85//! [2018]: https://blog.rust-lang.org/2018/12/06/Rust-1.31-and-rust-2018.html#rust-2018
86//! [crate]: https://crates.io/crates/cargo-emit
87//! [`Cargo.toml`]: https://doc.rust-lang.org/cargo/reference/manifest.html
88//! [`build.rs`]: https://doc.rust-lang.org/cargo/reference/build-scripts.html
89
90#![doc(html_root_url = "https://docs.rs/cargo-emit/0.1.1")]
91#![doc(
92 html_logo_url = "https://raw.githubusercontent.com/nvzqz/cargo-emit/assets/logo.svg?sanitize=true"
93)]
94#![deny(missing_docs)]
95
96/// `cargo:$key=$value`
97mod pair;
98/// `cargo:rerun-if-changed=$path`
99mod rerun_if_changed;
100/// `cargo:rerun-if-env-changed=$key`
101mod rerun_if_env_changed;
102/// `cargo:rustc-cdylib-link-arg=$flag`
103mod rustc_cdylib_link_arg;
104/// `cargo:rustc-cfg=$feature`
105mod rustc_cfg;
106/// `cargo:rustc-env=$key=$value`
107mod rustc_env;
108/// `cargo:rustc-flags=$flags`
109mod rustc_flags;
110/// `cargo:rustc-link-arg=$arg`
111mod rustc_link_arg;
112/// `cargo:rustc-link-arg-bin=$bin=$arg`
113mod rustc_link_arg_bin;
114/// `cargo:rustc-link-arg-bins=$arg`
115mod rustc_link_arg_bins;
116/// `cargo:rustc-link-lib=$kind=$name`
117mod rustc_link_lib;
118/// `cargo:rustc-link-search=$kind=$path`
119mod rustc_link_search;
120/// `cargo:warning=$message`
121mod warning;
122
123#[cfg(test)]
124fn capture_output<F>(f: F) -> String
125where
126 F: FnOnce(&mut String),
127{
128 let mut output = String::new();
129 f(&mut output);
130 output
131}