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

vergen_git2/
lib.rs
