1 // Copyright (c) 2016, 2018 vergen developers
2 //
3 // Licensed under the Apache License, Version 2.0
4 // <LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0> or the MIT
5 // license <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
6 // option. All files in the project carrying such notice may not be copied,
7 // modified, or distributed except according to those terms.
8 
9 //! # Generate Build Time Information
10 //! `vergen`, when used in conjunction with cargo [build scripts], will
11 //! generate environment variables to use with the `env!` macro.  Below
12 //! is a list of the supported variables.
13 //!
14 //! Key                       | Sample Value
15 //! --------------------------|----------------------------------------
16 //! VERGEN_BUILD_TIMESTAMP    |2018-08-09T15:15:57.282334589+00:000
17 //! VERGEN_BUILD_DATE         |2018-08-09
18 //! VERGEN_SHA                |75b390dc6c05a6a4aa2791cc7b3934591803bc22
19 //! VERGEN_SHA_SHORT          |75b390d
20 //! VERGEN_COMMIT_DATE        |2018-08-08
21 //! VERGEN_TARGET_TRIPLE      |x86_64-unknown-linux-gnu
22 //! VERGEN_SEMVER             |v0.1.0
23 //! VERGEN_SEMVER_LIGHTWEIGHT |v0.1.0
24 //!
25 //! The variable generation can be toggled on or off at an individual level
26 //! via [ConstantsFlags](crate::constants::ConstantsFlags)
27 //!
28 //! ### Note on SEMVER
29 //! `VERGEN_SEMVER` can be generated via `git describe` or by
30 //! `env::var("CARGO_PKG_VERSION")`.
31 //!
32 //! By default, `SEMVER` uses `git describe` if possible, and falls back to `CARGO_PKG_VERSION`.
33 //!
34 //! If you wish to force `CARGO_PKG_VERSION`, toggle off `SEMVER` and toggle
35 //! on `SEMVER_FROM_CARGO_PKG`.
36 //!
37 //! # Re-build On Changed HEAD
38 //! `vergen` can also be configured to re-run `build.rs` when either `.git/HEAD` or
39 //! the file that `.git/HEAD` points at changes.
40 //!
41 //! This can behavior can be toggled on or of with the [REBUILD_ON_HEAD_CHANGE] flag.
42 //!
43 //! [REBUILD_ON_HEAD_CHANGE]: crate::constants::ConstantsFlags::REBUILD_ON_HEAD_CHANGE
44 //! [build scripts]: https://doc.rust-lang.org/cargo/reference/build-scripts.html
45 //!
46 //! ## 'cargo:' Key Build Script Output
47 //! ```toml
48 //! [package]
49 //! #..
50 //! build = "build.rs"
51 //!
52 //! [dependencies]
53 //! #..
54 //!
55 //! [build-dependencies]
56 //! vergen = "3"
57 //! ```
58 //!
59 //! ### Example 'build.rs'
60 //! ```
61 //! use vergen::{ConstantsFlags, generate_cargo_keys};
62 //!
63 //! // Setup the flags, toggling off the 'SEMVER_FROM_CARGO_PKG' flag
64 //! let mut flags = ConstantsFlags::all();
65 //! flags.toggle(ConstantsFlags::SEMVER_FROM_CARGO_PKG);
66 //!
67 //! // Generate the 'cargo:' key output
68 //! generate_cargo_keys(flags).expect("Unable to generate the cargo keys!");
69 //! ```
70 //!
71 //! ### Use the constants in your code
72 //! ```
73 //! fn my_fn() {
74 //!     println!("Build Timestamp: {}", env!("VERGEN_BUILD_TIMESTAMP"));
75 //! }
76 //! ```
77 //!
78 //! ## **DEPRECATED** - `version.rs` File Build Script Output
79 //! Generate a `version.rs` file in `OUT_DIR` (defined by cargo) with up to 8 build time
80 //! constants.  This file can then be used with the `include!` macro to pull the
81 //! constants into your source for use.
82 //!
83 //! See the [generate_version_rs](crate::output::codegen::generate_version_rs) documentation
84 //! if you wish to use this method.
85 #![deny(
86   missing_docs,
87   missing_debug_implementations,
88   missing_copy_implementations,
89   trivial_casts,
90   trivial_numeric_casts,
91   unsafe_code,
92   unused_import_braces,
93   unused_qualifications
94 )]
95 #[macro_use]
96 extern crate bitflags;
97 #[cfg(test)]
98 extern crate lazy_static;
99 
100 mod constants;
101 mod output;
102 
103 pub use crate::constants::ConstantsFlags;
104 pub use crate::output::envvar::generate_cargo_keys;
105 use std::error::Error;
106 use std::fmt::{self, Display, Formatter};
107 
108 #[derive(Clone, Debug)]
109 /// An error generated by Vergen
110 pub struct VergenError {
111   description: String,
112 }
113 
114 impl VergenError {
115   /// Create an error struct
new<T: Into<String>>(description: T) -> Self116   pub fn new<T: Into<String>>(description: T) -> Self {
117     VergenError { description: description.into() }
118   }
119 }
120 
121 impl Display for VergenError {
fmt(&self, f: &mut Formatter<'_>) -> Result<(), fmt::Error>122   fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), fmt::Error> {
123     write!(f, "{}", self.description)
124   }
125 }
126 
127 impl Error for VergenError {}
128