vergen_gitcl/
lib.rs

1// Copyright (c) 2022 vergen developers
2//
3// Licensed under the Apache License, Version 2.0
4// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0> or the MIT
5// license <LICENSE-MIT or https://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//! # vergen-gitcl - Emit cargo instructions from a build script
10//! `vergen-gitcl` uses [`git`](https://git-scm.com/) from the command line to generate the git instructions.
11//!
12//! `vergen-gitcl`, when used in conjunction with cargo [build scripts] can emit the following:
13//!
14//! - Will emit [`cargo:rustc-env=VAR=VALUE`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#cargorustc-envvarvalue)
15//!   for each feature you have enabled.  These can be referenced with the [`env`!](std::env!) or [`option_env`!](std::option_env!) macro in your code.
16//! - Can emit [`cargo:warning`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#cargo-warning) outputs if the
17//!   [`fail_on_error`](Emitter::fail_on_error) feature is not enabled and the requested variable is defaulted through error or
18//!   the [`idempotent`](Emitter::idempotent) flag.
19//! - Will emit [`cargo:rerun-if-changed=.git/HEAD`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed)
20//!   if git instructions are emitted.  This is done to ensure any git instructions are regenerated when commits are made.
21//! - Will emit [`cargo:rerun-if-changed=.git/<path_to_ref>`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed)
22//!   if git instructions are emitted.  This is done to ensure any git instructions are regenerated when commits are made.
23//! - Will emit [`cargo:rerun-if-changed=build.rs`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed)
24//!   to rerun instruction emission if the `build.rs` file changed.
25//! - Will emit [`cargo:rerun-if-env-changed=VERGEN_IDEMPOTENT`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed)
26//!   to rerun instruction emission if the `VERGEN_IDEMPOTENT` environment variable has changed.
27//! - Will emit [`cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed)
28//!   to rerun instruction emission if the `SOURCE_DATE_EPOCH` environment variable has changed.
29//!
30//! ## Usage
31//!
32//! 1. Ensure you have build scripts enabled via the `build` configuration in your `Cargo.toml`
33//!
34//! ```toml
35//! [package]
36//! #..
37//! build = "build.rs"
38//! ```
39//!
40//! 2. Add `vergen-gitcl` as a build dependency in `Cargo.toml`, specifying the features you wish to enable.
41//!
42//! ```toml
43//! [dependencies]
44//! #..
45//!
46//! [build-dependencies]
47//! # All features enabled
48//! vergen-gitcl = { version = "1.0.0", features = ["build", "cargo", "rustc", "si"] }
49//! # or
50//! vergen-gitcl = { version = "1.0.0", features = ["build"] }
51//! # if you wish to disable certain features
52//! ```
53//!
54//! 3. Create a `build.rs` file that uses `vergen-gitcl` to emit cargo instructions.  Configuration
55//!    starts with [`Emitter`].  Eventually you will call [`emit`](Emitter::emit) to output the
56//!    cargo instructions. See the [`emit`](Emitter::emit) documentation for more robust examples.
57//!
58//! #### Generate all output
59//!
60//! ```
61//! # use anyhow::Result;
62//! # use vergen_gitcl::{Emitter, Gitcl};
63#![cfg_attr(feature = "build", doc = r"# use vergen_gitcl::Build;")]
64#![cfg_attr(feature = "cargo", doc = r"# use vergen_gitcl::Cargo;")]
65#![cfg_attr(feature = "rustc", doc = r"# use vergen_gitcl::Rustc;")]
66#![cfg_attr(feature = "si", doc = r"# use vergen_gitcl::Sysinfo;")]
67#![cfg_attr(feature = "cargo", doc = r"# use test_util::with_cargo_vars;")]
68//! #
69//! # pub fn main() -> Result<()> {
70#![cfg_attr(feature = "cargo", doc = r"# let result = with_cargo_vars(|| {")]
71//! // NOTE: This will output everything, and requires all features enabled.
72//! // NOTE: See the specific builder documentation for configuration options.
73#![cfg_attr(feature = "build", doc = r"let build = Build::all_build();")]
74#![cfg_attr(feature = "cargo", doc = r"let cargo = Cargo::all_cargo();")]
75//! let gitcl = Gitcl::all_git();
76#![cfg_attr(feature = "rustc", doc = r"let rustc = Rustc::all_rustc();")]
77#![cfg_attr(feature = "si", doc = r"let si = Sysinfo::all_sysinfo();")]
78//!
79//! Emitter::default()
80#![cfg_attr(feature = "build", doc = r"    .add_instructions(&build)?")]
81#![cfg_attr(feature = "cargo", doc = r"    .add_instructions(&cargo)?")]
82//!     .add_instructions(&gitcl)?
83#![cfg_attr(feature = "rustc", doc = r"    .add_instructions(&rustc)?")]
84#![cfg_attr(feature = "si", doc = r"    .add_instructions(&si)?")]
85//!     .emit()?;
86#![cfg_attr(
87    feature = "cargo",
88    doc = r"
89# Ok(())
90# });
91# assert!(result.is_ok());"
92)]
93//! #    Ok(())
94//! # }
95//! ```
96//! #### Sample Output
97//! ```text
98//! cargo:rustc-env=VERGEN_BUILD_DATE=2024-01-31
99//! cargo:rustc-env=VERGEN_BUILD_TIMESTAMP=2024-01-31T03:26:34.065893658Z
100//! cargo:rustc-env=VERGEN_CARGO_DEBUG=true
101//! cargo:rustc-env=VERGEN_CARGO_FEATURES=
102//! cargo:rustc-env=VERGEN_CARGO_OPT_LEVEL=0
103//! cargo:rustc-env=VERGEN_CARGO_TARGET_TRIPLE=x86_64-unknown-linux-gnu
104//! cargo:rustc-env=VERGEN_CARGO_DEPENDENCIES=anyhow 1.0.79,vergen-pretty 0.3.2
105//! cargo:rustc-env=VERGEN_GIT_BRANCH=master
106//! cargo:rustc-env=VERGEN_GIT_COMMIT_AUTHOR_EMAIL=emitter@vergen.com
107//! cargo:rustc-env=VERGEN_GIT_COMMIT_AUTHOR_NAME=Jason Ozias
108//! cargo:rustc-env=VERGEN_GIT_COMMIT_COUNT=44
109//! cargo:rustc-env=VERGEN_GIT_COMMIT_DATE=2024-01-30
110//! cargo:rustc-env=VERGEN_GIT_COMMIT_MESSAGE=depsup
111//! cargo:rustc-env=VERGEN_GIT_COMMIT_TIMESTAMP=2024-01-30T21:43:43.000000000Z
112//! cargo:rustc-env=VERGEN_GIT_DESCRIBE=0.1.0-beta.1-15-g728e25c
113//! cargo:rustc-env=VERGEN_GIT_DIRTY=false
114//! cargo:rustc-env=VERGEN_GIT_SHA=728e25ca5bb7edbbc505f12b28c66b2b27883cf1
115//! cargo:rustc-env=VERGEN_RUSTC_CHANNEL=nightly
116//! cargo:rustc-env=VERGEN_RUSTC_COMMIT_DATE=2024-01-29
117//! cargo:rustc-env=VERGEN_RUSTC_COMMIT_HASH=5518eaa946291f00471af8b254b2a1715f234882
118//! cargo:rustc-env=VERGEN_RUSTC_HOST_TRIPLE=x86_64-unknown-linux-gnu
119//! cargo:rustc-env=VERGEN_RUSTC_LLVM_VERSION=17.0
120//! cargo:rustc-env=VERGEN_RUSTC_SEMVER=1.77.0-nightly
121//! cargo:rustc-env=VERGEN_SYSINFO_NAME=Arch Linux
122//! cargo:rustc-env=VERGEN_SYSINFO_OS_VERSION=Linux  Arch Linux
123//! cargo:rustc-env=VERGEN_SYSINFO_USER=jozias
124//! cargo:rustc-env=VERGEN_SYSINFO_TOTAL_MEMORY=31 GiB
125//! cargo:rustc-env=VERGEN_SYSINFO_CPU_VENDOR=AuthenticAMD
126//! cargo:rustc-env=VERGEN_SYSINFO_CPU_CORE_COUNT=8
127//! cargo:rustc-env=VERGEN_SYSINFO_CPU_NAME=cpu0,cpu1,cpu2,cpu3,cpu4,cpu5,cpu6,cpu7
128//! cargo:rustc-env=VERGEN_SYSINFO_CPU_BRAND=AMD Ryzen Threadripper 1900X 8-Core Processor
129//! cargo:rustc-env=VERGEN_SYSINFO_CPU_FREQUENCY=3792
130//! cargo:rerun-if-changed=/home/jozias/projects/rust-lang/vergen-cl/.git/HEAD
131//! cargo:rerun-if-changed=/home/jozias/projects/rust-lang/vergen-cl/.git/refs/heads/master
132//! cargo:rerun-if-changed=build.rs
133//! cargo:rerun-if-env-changed=VERGEN_IDEMPOTENT
134//! cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH
135//! ```
136//!
137//! #### Generate specific output
138//!
139//! ```
140//! # use anyhow::Result;
141//! # use vergen_gitcl::{Emitter, Gitcl};
142#![cfg_attr(feature = "build", doc = r"# use vergen_gitcl::Build;")]
143#![cfg_attr(feature = "cargo", doc = r"# use vergen_gitcl::Cargo;")]
144#![cfg_attr(feature = "rustc", doc = r"# use vergen_gitcl::Rustc;")]
145#![cfg_attr(feature = "si", doc = r"# use vergen_gitcl::Sysinfo;")]
146#![cfg_attr(feature = "cargo", doc = r"# use test_util::with_cargo_vars;")]
147//! #
148//! # pub fn main() -> Result<()> {
149#![cfg_attr(feature = "cargo", doc = r"# let result = with_cargo_vars(|| {")]
150#![cfg_attr(
151    feature = "build",
152    doc = r"// NOTE: This will output only the instructions specified.
153// NOTE: See the specific builder documentation for configuration options. 
154let build = Build::builder().build_timestamp(true).build();"
155)]
156#![cfg_attr(
157    feature = "cargo",
158    doc = r"let cargo = Cargo::builder().opt_level(true).build();"
159)]
160//! let gitcl = Gitcl::builder().commit_timestamp(true).build();
161#![cfg_attr(
162    feature = "rustc",
163    doc = r"let rustc = Rustc::builder().semver(true).build();"
164)]
165#![cfg_attr(
166    feature = "si",
167    doc = r"let si = Sysinfo::builder().cpu_core_count(true).build();"
168)]
169//!
170//! Emitter::default()
171#![cfg_attr(feature = "build", doc = r"    .add_instructions(&build)?")]
172#![cfg_attr(feature = "cargo", doc = r"    .add_instructions(&cargo)?")]
173//!     .add_instructions(&gitcl)?
174#![cfg_attr(feature = "rustc", doc = r"    .add_instructions(&rustc)?")]
175#![cfg_attr(feature = "si", doc = r"    .add_instructions(&si)?")]
176//!     .emit()?;
177#![cfg_attr(
178    feature = "cargo",
179    doc = r"
180#   Ok(())
181# });
182# assert!(result.is_ok());"
183)]
184//! #     Ok(())
185//! # }
186//! ```
187//! #### Sample Output
188//! ```text
189//! cargo:rustc-env=VERGEN_BUILD_TIMESTAMP=2024-01-31T03:26:34.065893658Z
190//! cargo:rustc-env=VERGEN_CARGO_OPT_LEVEL=0
191//! cargo:rustc-env=VERGEN_GIT_COMMIT_TIMESTAMP=2024-01-30T21:43:43.000000000Z
192//! cargo:rustc-env=VERGEN_RUSTC_SEMVER=1.77.0-nightly
193//! cargo:rustc-env=VERGEN_SYSINFO_CPU_CORE_COUNT=8
194//! cargo:rerun-if-changed=/home/jozias/projects/rust-lang/vergen-cl/.git/HEAD
195//! cargo:rerun-if-changed=/home/jozias/projects/rust-lang/vergen-cl/.git/refs/heads/master
196//! cargo:rerun-if-changed=build.rs
197//! cargo:rerun-if-env-changed=VERGEN_IDEMPOTENT
198//! cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH
199//! ```
200//!
201//! 4. Use the [`env!`](std::env!) or [`option_env!`](std::option_env!) macro in your code to read the environment variables.
202//!
203//! ```
204//! if let Some(timestamp) = option_env!("VERGEN_BUILD_TIMESTAMP") {
205//!     println!("Build Timestamp: {timestamp}");
206//! }
207//! if let Some(describe) = option_env!("VERGEN_GIT_DESCRIBE") {
208//!     println!("git describe: {describe}");
209//! }
210//! ```
211//!
212//! ## Features
213//! `vergen-gitcl` has four main feature toggles allowing you to customize your output. No features are enabled by default.
214//! You **must** specifically enable the features you wish to use.
215//!
216//! | Feature | Enables |
217//! | ------- | ------- |
218//! |  build  | `VERGEN_BUILD_*` instructions |
219//! |  cargo  | `VERGEN_CARGO_*` instructions |
220//! |  rustc  | `VERGEN_RUSTC_*` instructions |
221//! |   si    | `VERGEN_SYSINFO_*` instructions |
222//!
223//! ## Environment Variables
224//! `vergen-gitcl` currently recognizes the following environment variables. The full list of the environment variable names can be
225//! found as [constants here](https://docs.rs/vergen-lib/latest/vergen_lib/constants/features/index.html)
226//!
227//! | Variable | Functionality |
228//! | -------- | ------------- |
229//! | `VERGEN_IDEMPOTENT` | If this environment variable is set `vergen` will use the idempotent output feature regardless of the configuration set in `build.rs`.  This exists mainly to allow package maintainers to force idempotent output to generate deterministic binary output. |
230//! | `SOURCE_DATE_EPOCH` | If this environment variable is set `vergen` will use the value (unix time since epoch) as the basis for a time based instructions.  This can help emit deterministic instructions. |
231//! | `VERGEN_BUILD_*` | If this environment variable is set `vergen` will use the value you specify for the output rather than generating it. |
232//! | `VERGEN_CARGO_*` | If this environment variable is set `vergen` will use the value you specify for the output rather than generating it. |
233//! | `VERGEN_GIT_*` | If this environment variable is set `vergen` will use the value you specify for the output rather than generating it. |
234//! | `VERGEN_RUSTC_*` | If this environment variable is set `vergen` will use the value you specify for the output rather than generating it. |
235//! | `VERGEN_SYSINFO_*` | If this environment variable is set `vergen` will use the value you specify for the output rather than generating it. |
236//!
237//! [build scripts]: https://doc.rust-lang.org/cargo/reference/build-scripts.html#outputs-of-the-build-script
238//! [cargo:rustc-env]: https://doc.rust-lang.org/cargo/reference/build-scripts.html#rustc-env
239//! [cargo:rerun-if-changed]: https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed
240//!
241
242// rustc lints
243#![cfg_attr(
244    all(feature = "unstable", nightly),
245    feature(
246        multiple_supertrait_upcastable,
247        must_not_suspend,
248        non_exhaustive_omitted_patterns_lint,
249        strict_provenance_lints,
250        unqualified_local_imports,
251    )
252)]
253#![cfg_attr(nightly, allow(single_use_lifetimes, unexpected_cfgs))]
254#![cfg_attr(
255    nightly,
256    deny(
257        absolute_paths_not_starting_with_crate,
258        ambiguous_glob_imports,
259        ambiguous_glob_reexports,
260        ambiguous_negative_literals,
261        ambiguous_wide_pointer_comparisons,
262        anonymous_parameters,
263        array_into_iter,
264        asm_sub_register,
265        async_fn_in_trait,
266        bad_asm_style,
267        bare_trait_objects,
268        boxed_slice_into_iter,
269        break_with_label_and_loop,
270        clashing_extern_declarations,
271        closure_returning_async_block,
272        coherence_leak_check,
273        confusable_idents,
274        const_evaluatable_unchecked,
275        const_item_mutation,
276        dangling_pointers_from_temporaries,
277        dead_code,
278        dependency_on_unit_never_type_fallback,
279        deprecated,
280        deprecated_in_future,
281        deprecated_safe_2024,
282        deprecated_where_clause_location,
283        deref_into_dyn_supertrait,
284        deref_nullptr,
285        double_negations,
286        drop_bounds,
287        dropping_copy_types,
288        dropping_references,
289        duplicate_macro_attributes,
290        dyn_drop,
291        edition_2024_expr_fragment_specifier,
292        elided_lifetimes_in_paths,
293        ellipsis_inclusive_range_patterns,
294        explicit_outlives_requirements,
295        exported_private_dependencies,
296        ffi_unwind_calls,
297        forbidden_lint_groups,
298        forgetting_copy_types,
299        forgetting_references,
300        for_loops_over_fallibles,
301        function_item_references,
302        hidden_glob_reexports,
303        if_let_rescope,
304        impl_trait_overcaptures,
305        impl_trait_redundant_captures,
306        improper_ctypes,
307        improper_ctypes_definitions,
308        inline_no_sanitize,
309        internal_features,
310        invalid_from_utf8,
311        invalid_macro_export_arguments,
312        invalid_nan_comparisons,
313        invalid_value,
314        irrefutable_let_patterns,
315        keyword_idents_2018,
316        keyword_idents_2024,
317        large_assignments,
318        late_bound_lifetime_arguments,
319        legacy_derive_helpers,
320        let_underscore_drop,
321        macro_use_extern_crate,
322        map_unit_fn,
323        meta_variable_misuse,
324        mismatched_lifetime_syntaxes,
325        missing_abi,
326        missing_copy_implementations,
327        missing_debug_implementations,
328        missing_docs,
329        missing_unsafe_on_extern,
330        mixed_script_confusables,
331        named_arguments_used_positionally,
332        never_type_fallback_flowing_into_unsafe,
333        no_mangle_generic_items,
334        non_ascii_idents,
335        non_camel_case_types,
336        non_contiguous_range_endpoints,
337        non_fmt_panics,
338        non_local_definitions,
339        non_shorthand_field_patterns,
340        non_snake_case,
341        non_upper_case_globals,
342        noop_method_call,
343        opaque_hidden_inferred_bound,
344        out_of_scope_macro_calls,
345        overlapping_range_endpoints,
346        path_statements,
347        private_bounds,
348        private_interfaces,
349        ptr_to_integer_transmute_in_consts,
350        redundant_imports,
351        redundant_lifetimes,
352        redundant_semicolons,
353        refining_impl_trait_internal,
354        refining_impl_trait_reachable,
355        renamed_and_removed_lints,
356        repr_transparent_non_zst_fields,
357        rust_2021_incompatible_closure_captures,
358        rust_2021_incompatible_or_patterns,
359        rust_2021_prefixes_incompatible_syntax,
360        rust_2021_prelude_collisions,
361        rust_2024_guarded_string_incompatible_syntax,
362        rust_2024_incompatible_pat,
363        rust_2024_prelude_collisions,
364        self_constructor_from_outer_item,
365        semicolon_in_expressions_from_macros,
366        single_use_lifetimes,
367        special_module_name,
368        stable_features,
369        static_mut_refs,
370        suspicious_double_ref_op,
371        tail_expr_drop_order,
372        trivial_bounds,
373        trivial_casts,
374        trivial_numeric_casts,
375        type_alias_bounds,
376        tyvar_behind_raw_pointer,
377        uncommon_codepoints,
378        unconditional_recursion,
379        uncovered_param_in_projection,
380        unfulfilled_lint_expectations,
381        ungated_async_fn_track_caller,
382        uninhabited_static,
383        unit_bindings,
384        unknown_lints,
385        unknown_or_malformed_diagnostic_attributes,
386        unnameable_test_items,
387        unnameable_types,
388        unpredictable_function_pointer_comparisons,
389        unreachable_code,
390        unreachable_patterns,
391        unreachable_pub,
392        unsafe_attr_outside_unsafe,
393        unsafe_code,
394        unsafe_op_in_unsafe_fn,
395        unstable_name_collisions,
396        unstable_syntax_pre_expansion,
397        unused_allocation,
398        unused_assignments,
399        unused_associated_type_bounds,
400        unused_attributes,
401        unused_braces,
402        unused_comparisons,
403        unused_crate_dependencies,
404        unused_doc_comments,
405        unused_extern_crates,
406        unused_features,
407        unused_import_braces,
408        unused_imports,
409        unused_labels,
410        unused_lifetimes,
411        unused_macro_rules,
412        unused_macros,
413        unused_must_use,
414        unused_mut,
415        unused_parens,
416        unused_qualifications,
417        unused_results,
418        unused_unsafe,
419        unused_variables,
420        useless_ptr_null_checks,
421        uses_power_alignment,
422        variant_size_differences,
423        while_true,
424    )
425)]
426// If nightly and unstable, allow `incomplete_features` and `unstable_features`
427#![cfg_attr(
428    all(feature = "unstable", nightly),
429    allow(incomplete_features, unstable_features)
430)]
431// If nightly and not unstable, deny `incomplete_features` and `unstable_features`
432#![cfg_attr(
433    all(not(feature = "unstable"), nightly),
434    deny(incomplete_features, unstable_features)
435)]
436// The unstable lints
437#![cfg_attr(
438    all(feature = "unstable", nightly),
439    deny(
440        fuzzy_provenance_casts,
441        lossy_provenance_casts,
442        multiple_supertrait_upcastable,
443        must_not_suspend,
444        non_exhaustive_omitted_patterns,
445        unqualified_local_imports,
446    )
447)]
448// clippy lints
449#![cfg_attr(nightly, deny(clippy::all, clippy::pedantic))]
450// rustdoc lints
451#![cfg_attr(
452    nightly,
453    deny(
454        rustdoc::bare_urls,
455        rustdoc::broken_intra_doc_links,
456        rustdoc::invalid_codeblock_attributes,
457        rustdoc::invalid_html_tags,
458        rustdoc::missing_crate_level_docs,
459        rustdoc::private_doc_tests,
460        rustdoc::private_intra_doc_links,
461    )
462)]
463#![cfg_attr(all(docsrs, nightly), feature(doc_cfg))]
464#![cfg_attr(all(nightly, coverage_nightly), feature(coverage_attribute))]
465
466#[cfg(test)]
467use {regex as _, temp_env as _};
468// This is here to appease the `unused_crate_dependencies` lint
469#[cfg(not(any(
470    feature = "build",
471    feature = "cargo",
472    feature = "rustc",
473    feature = "si"
474)))]
475use vergen as _;
476
477mod gitcl;
478
479pub use self::gitcl::Gitcl;
480#[cfg(feature = "build")]
481pub use vergen::Build;
482#[cfg(feature = "cargo")]
483pub use vergen::Cargo;
484#[cfg(feature = "si")]
485pub use vergen::CpuRefreshKind;
486#[cfg(feature = "cargo_metadata")]
487pub use vergen::DependencyKind;
488#[cfg(feature = "si")]
489pub use vergen::MemoryRefreshKind;
490#[cfg(feature = "si")]
491pub use vergen::ProcessRefreshKind;
492#[cfg(feature = "si")]
493pub use vergen::RefreshKind;
494#[cfg(feature = "rustc")]
495pub use vergen::Rustc;
496#[cfg(feature = "si")]
497pub use vergen::Sysinfo;
498pub use vergen_lib::AddCustomEntries;
499pub use vergen_lib::CargoRerunIfChanged;
500pub use vergen_lib::CargoWarning;
501pub use vergen_lib::DefaultConfig;
502pub use vergen_lib::Emitter;
vergen_gitcl/lib.rs

vergen_gitcl/
lib.rs
