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