oysterpack_built/
lib.rs

1// Copyright 2018 OysterPack Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! From a DevOps perspective, it is critical to know exactly what is deployed.
16//! `oysterpack_built` is used as a build-time dependency to gather application build related metadata.
17//! The information is gathered from the cargo build. It produces a Rust source file named **built.rs**
18//! in the project's build script output directory. The location can be obtained via:
19//!
20//! ```ignore
21//! let built_rs = concat!(env!("OUT_DIR"), "/built.rs");
22//! ```
23//!
24//! ## How to integrate within your project
25//! This crate meant to be used in conjunction with [oysterpack_app_metadata](https://crates.io/crates/oysterpack_app_metadata).
26//! This crate generates the application build metadata source file.
27//! [oysterpack_app_metadata](https://crates.io/crates/oysterpack_app_metadata) is used to load the application build netadata.
28//!
29//! 1. Add the following to **Cargo.toml**:
30//!
31//!    ```toml
32//!    [package]
33//!    build = "build.rs"
34//!
35//!    [dependencies]
36//!    oysterpack_app_metadata = "0.1"
37//!    semver = "0.9"
38//!    chrono = "0.4"
39//!
40//!    [build-dependencies]
41//!    oysterpack_built = "0.3"
42//!    ```
43//!    - `oysterpack_built` is added as a build dependency
44//!    - `build.rs` is the name of the cargo build script to use
45//!    - [oysterpack_app_metadata][oysterpack_app_metadata] is used in conjuction with this crate to
46//!      load the application build metadata into the domain model defined by [oysterpack_app_metadata][oysterpack_app_metadata]
47//!
48//! [oysterpack_app_metadata]: https://crates.io/crates/oysterpack_app_metadata
49//!
50//! 2. Include the following in **build.rs**:
51//!
52//!    ```ignore
53//!    extern crate oysterpack_built;
54//!
55//!    fn main() {
56//!       oysterpack_built::run();
57//!    }
58//!    ```
59//!
60//! 3. The build script will write a file named **built.rs** into Cargo's build output directory,
61//!    which will contain the following constants:
62//!
63//! Constant | Type | Description
64//! -------- | ---- | -----------
65//! BUILT_TIME_UTC|&str|The built-time in RFC822, UTC
66//! CFG_ENDIAN|&str|The endianness, given by cfg!(target_endian).
67//! CFG_ENV|&str|The toolchain-environment, given by cfg!(target_env).
68//! CFG_FAMILY|&str|The OS-family, given by cfg!(target_family).
69//! CFG_OS|&str|The operating system, given by cfg!(target_os).
70//! CFG_POINTER_WIDTH|u8|The pointer width, given by cfg!(target_pointer_width).
71//! CFG_TARGET_ARCH|&str|The target architecture, given by cfg!(target_arch).
72//! CI_PLATFORM|Option<&str>|The Continuous Integration platform detected during compilation.
73//! DEBUG|bool|Value of DEBUG for the profile used during compilation.
74//! FEATURES|\[&str; N\]|The features that were enabled during compilation.
75//! FEATURES_STR|&str|The features as a comma-separated string.
76//! GIT_VERSION|Option<&str>|If the crate was compiled from within a git-repository, GIT_VERSION contains HEAD's tag. The short commit id is used if HEAD is not tagged.
77//! HOST|&str|The host triple of the rust compiler.
78//! NUM_JOBS|u32|The parallelism that was specified during compilation.
79//! OPT_LEVEL|&str|Value of OPT_LEVEL for the profile used during compilation.
80//! PKG_AUTHORS|&str|A colon-separated list of authors.
81//! PKG_DESCRIPTION|&str|The description.
82//! PKG_HOMEPAGE|&str|The homepage.
83//! PKG_NAME|&str|The name of the package.
84//! PKG_VERSION|&str|The full version.
85//! PKG_VERSION_MAJOR|&str|The major version.
86//! PKG_VERSION_MINOR|&str|The minor version.
87//! PKG_VERSION_PATCH|&str|The patch version.
88//! PKG_VERSION_PRE|&str|The pre-release version.
89//! PROFILE|&str|release for release builds, debug for other builds.
90//! RUSTC|&str|The compiler that cargo resolved to use.
91//! RUSTC_VERSION|&str|The output of rustc -V
92//! RUSTDOC|&str|The documentation generator that cargo resolved to use.
93//! RUSTDOC_VERSION|&str|The output of rustdoc -V
94//! DEPENDENCIES_GRAPHVIZ_DOT|&str|graphviz .dot format for the effective dependency graph
95//!
96//! The application metadata can be loaded via [oysterpack_app_metadata op_build_mod!()](https://docs.rs/oysterpack_app_metadata/latest/oysterpack_app_metadata/macro.op_build_mod.html)):
97//!
98//! ```ignore
99//! #[macro_use]
100//! extern crate oysterpack_app_metadata;
101//! extern crate chrono;
102//! extern crate semver;
103//!
104//! // loads the application metadata into `pub mod build {...}'
105//! op_build_mod!()
106//!
107//! use oysterpack_app_metadata::Build;
108//!
109//! fn main () {
110//!     let app_build = build::get();
111//!     // integrate the application build metadata ...
112//! }
113//! ```
114
115#![deny(missing_docs, missing_debug_implementations)]
116#![doc(html_root_url = "https://docs.rs/oysterpack_built/0.3.2")]
117
118#[allow(unused_imports)]
119#[macro_use]
120extern crate log;
121extern crate chrono;
122extern crate semver;
123extern crate serde;
124#[macro_use]
125extern crate serde_derive;
126
127extern crate built;
128extern crate cargo;
129extern crate failure;
130extern crate petgraph;
131
132#[macro_use]
133#[cfg(test)]
134extern crate oysterpack_testing;
135#[cfg(test)]
136extern crate serde_json;
137
138pub mod build_time;
139pub use build_time::run;
140
141#[cfg(test)]
142op_tests_mod!();
oysterpack_built/lib.rs

oysterpack_built/
lib.rs
