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=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-git2` 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-git2 = { version = "1.0.0", features = ["build", "cargo", "rustc", "si"] }
49//! # or
50//! vergen-git2 = { 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-git2` 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_git2::{Emitter, Git2Builder};
63#![cfg_attr(feature = "build", doc = r"# use vergen_git2::BuildBuilder;")]
64#![cfg_attr(feature = "cargo", doc = r"# use vergen_git2::CargoBuilder;")]
65#![cfg_attr(feature = "rustc", doc = r"# use vergen_git2::RustcBuilder;")]
66#![cfg_attr(feature = "si", doc = r"# use vergen_git2::SysinfoBuilder;")]
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 = BuildBuilder::all_build()?;")]
74#![cfg_attr(feature = "cargo", doc = r"let cargo = CargoBuilder::all_cargo()?;")]
75//! let git2 = Git2Builder::all_git()?;
76#![cfg_attr(feature = "rustc", doc = r"let rustc = RustcBuilder::all_rustc()?;")]
77#![cfg_attr(feature = "si", doc = r"let si = SysinfoBuilder::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(&git2)?
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_SHA=728e25ca5bb7edbbc505f12b28c66b2b27883cf1
114//! cargo:rustc-env=VERGEN_RUSTC_CHANNEL=nightly
115//! cargo:rustc-env=VERGEN_RUSTC_COMMIT_DATE=2024-01-29
116//! cargo:rustc-env=VERGEN_RUSTC_COMMIT_HASH=5518eaa946291f00471af8b254b2a1715f234882
117//! cargo:rustc-env=VERGEN_RUSTC_HOST_TRIPLE=x86_64-unknown-linux-gnu
118//! cargo:rustc-env=VERGEN_RUSTC_LLVM_VERSION=17.0
119//! cargo:rustc-env=VERGEN_RUSTC_SEMVER=1.77.0-nightly
120//! cargo:rustc-env=VERGEN_SYSINFO_NAME=Arch Linux
121//! cargo:rustc-env=VERGEN_SYSINFO_OS_VERSION=Linux Arch Linux
122//! cargo:rustc-env=VERGEN_SYSINFO_USER=jozias
123//! cargo:rustc-env=VERGEN_SYSINFO_TOTAL_MEMORY=31 GiB
124//! cargo:rustc-env=VERGEN_SYSINFO_CPU_VENDOR=AuthenticAMD
125//! cargo:rustc-env=VERGEN_SYSINFO_CPU_CORE_COUNT=8
126//! cargo:rustc-env=VERGEN_SYSINFO_CPU_NAME=cpu0,cpu1,cpu2,cpu3,cpu4,cpu5,cpu6,cpu7
127//! cargo:rustc-env=VERGEN_SYSINFO_CPU_BRAND=AMD Ryzen Threadripper 1900X 8-Core Processor
128//! cargo:rustc-env=VERGEN_SYSINFO_CPU_FREQUENCY=3792
129//! cargo:rerun-if-changed=/home/jozias/projects/rust-lang/vergen-cl/.git/HEAD
130//! cargo:rerun-if-changed=/home/jozias/projects/rust-lang/vergen-cl/.git/refs/heads/master
131//! cargo:rerun-if-changed=build.rs
132//! cargo:rerun-if-env-changed=VERGEN_IDEMPOTENT
133//! cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH
134//! ```
135//!
136//! #### Generate specific output
137//!
138//! ```
139//! # use anyhow::Result;
140//! # use vergen_git2::{Emitter, Git2Builder};
141#![cfg_attr(feature = "build", doc = r"# use vergen_git2::BuildBuilder;")]
142#![cfg_attr(feature = "cargo", doc = r"# use vergen_git2::CargoBuilder;")]
143#![cfg_attr(feature = "rustc", doc = r"# use vergen_git2::RustcBuilder;")]
144#![cfg_attr(feature = "si", doc = r"# use vergen_git2::SysinfoBuilder;")]
145#![cfg_attr(feature = "cargo", doc = r"# use test_util::with_cargo_vars;")]
146//! #
147//! # pub fn main() -> Result<()> {
148#![cfg_attr(feature = "cargo", doc = r"# let result = with_cargo_vars(|| {")]
149#![cfg_attr(
150 feature = "build",
151 doc = r"// NOTE: This will output only the instructions specified.
152// NOTE: See the specific builder documentation for configuration options.
153let build = BuildBuilder::default().build_timestamp(true).build()?;"
154)]
155#![cfg_attr(
156 feature = "cargo",
157 doc = r"let cargo = CargoBuilder::default().opt_level(true).build()?;"
158)]
159//! let git2 = Git2Builder::default().commit_timestamp(true).build()?;
160#![cfg_attr(
161 feature = "rustc",
162 doc = r"let rustc = RustcBuilder::default().semver(true).build()?;"
163)]
164#![cfg_attr(
165 feature = "si",
166 doc = r"let si = SysinfoBuilder::default().cpu_core_count(true).build()?;"
167)]
168//!
169//! Emitter::default()
170#![cfg_attr(feature = "build", doc = r" .add_instructions(&build)?")]
171#![cfg_attr(feature = "cargo", doc = r" .add_instructions(&cargo)?")]
172//! .add_instructions(&git2)?
173#![cfg_attr(feature = "rustc", doc = r" .add_instructions(&rustc)?")]
174#![cfg_attr(feature = "si", doc = r" .add_instructions(&si)?")]
175//! .emit()?;
176#![cfg_attr(
177 feature = "cargo",
178 doc = r"
179# Ok(())
180# });
181# assert!(result.is_ok());"
182)]
183//! # Ok(())
184//! # }
185//! ```
186//! #### Sample Output
187//! ```text
188//! cargo:rustc-env=VERGEN_BUILD_TIMESTAMP=2024-01-31T03:26:34.065893658Z
189//! cargo:rustc-env=VERGEN_CARGO_OPT_LEVEL=0
190//! cargo:rustc-env=VERGEN_GIT_COMMIT_TIMESTAMP=2024-01-30T21:43:43.000000000Z
191//! cargo:rustc-env=VERGEN_RUSTC_SEMVER=1.77.0-nightly
192//! cargo:rustc-env=VERGEN_SYSINFO_CPU_CORE_COUNT=8
193//! cargo:rerun-if-changed=/home/jozias/projects/rust-lang/vergen-cl/.git/HEAD
194//! cargo:rerun-if-changed=/home/jozias/projects/rust-lang/vergen-cl/.git/refs/heads/master
195//! cargo:rerun-if-changed=build.rs
196//! cargo:rerun-if-env-changed=VERGEN_IDEMPOTENT
197//! cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH
198//! ```
199//!
200//! 4. Use the [`env!`](std::env!) or [`option_env!`](std::option_env!) macro in your code to read the environment variables.
201//!
202//! ```
203//! if let Some(timestamp) = option_env!("VERGEN_BUILD_TIMESTAMP") {
204//! println!("Build Timestamp: {timestamp}");
205//! }
206//! if let Some(describe) = option_env!("VERGEN_GIT_DESCRIBE") {
207//! println!("git describe: {describe}");
208//! }
209//! ```
210//!
211//! ## Features
212//! `vergen-git2` has four main feature toggles allowing you to customize your output. No features are enabled by default.
213//! You **must** specifically enable the features you wish to use.
214//!
215//! | Feature | Enables |
216//! | ------- | ------- |
217//! | build | `VERGEN_BUILD_*` instructions |
218//! | cargo | `VERGEN_CARGO_*` instructions |
219//! | rustc | `VERGEN_RUSTC_*` instructions |
220//! | si | `VERGEN_SYSINFO_*` instructions |
221//!
222//! ## Environment Variables
223//! `vergen-git2` currently recognizes the following environment variables. The full list of the environment variable names can be
224//! found as [constants here](https://docs.rs/vergen-lib/latest/vergen_lib/constants/features/index.html)
225//!
226//! | Variable | Functionality |
227//! | -------- | ------------- |
228//! | `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. |
229//! | `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. |
230//! | `VERGEN_BUILD_*` | If this environment variable is set `vergen` will use the value you specify for the output rather than generating it. |
231//! | `VERGEN_CARGO_*` | If this environment variable is set `vergen` will use the value you specify for the output rather than generating it. |
232//! | `VERGEN_GIT_*` | If this environment variable is set `vergen` will use the value you specify for the output rather than generating it. |
233//! | `VERGEN_RUSTC_*` | If this environment variable is set `vergen` will use the value you specify for the output rather than generating it. |
234//! | `VERGEN_SYSINFO_*` | If this environment variable is set `vergen` will use the value you specify for the output rather than generating it. |
235//!
236//! [build scripts]: https://doc.rust-lang.org/cargo/reference/build-scripts.html#outputs-of-the-build-script
237//! [cargo:rustc-env]: https://doc.rust-lang.org/cargo/reference/build-scripts.html#rustc-env
238//! [cargo:rerun-if-changed]: https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed
239//!
240
241// rustc lints
242#![cfg_attr(
243 all(feature = "unstable", nightly),
244 feature(
245 multiple_supertrait_upcastable,
246 must_not_suspend,
247 non_exhaustive_omitted_patterns_lint,
248 rustdoc_missing_doc_code_examples,
249 strict_provenance_lints,
250 )
251)]
252#![cfg_attr(nightly, allow(single_use_lifetimes, unexpected_cfgs))]
253#![cfg_attr(
254 nightly,
255 deny(
256 absolute_paths_not_starting_with_crate,
257 ambiguous_glob_imports,
258 ambiguous_glob_reexports,
259 ambiguous_wide_pointer_comparisons,
260 anonymous_parameters,
261 array_into_iter,
262 asm_sub_register,
263 async_fn_in_trait,
264 bad_asm_style,
265 bare_trait_objects,
266 break_with_label_and_loop,
267 clashing_extern_declarations,
268 coherence_leak_check,
269 confusable_idents,
270 const_evaluatable_unchecked,
271 const_item_mutation,
272 dangling_pointers_from_temporaries,
273 dead_code,
274 deprecated,
275 deprecated_in_future,
276 deprecated_where_clause_location,
277 deref_into_dyn_supertrait,
278 deref_nullptr,
279 drop_bounds,
280 dropping_copy_types,
281 dropping_references,
282 duplicate_macro_attributes,
283 dyn_drop,
284 elided_lifetimes_in_associated_constant,
285 elided_lifetimes_in_paths,
286 ellipsis_inclusive_range_patterns,
287 explicit_outlives_requirements,
288 exported_private_dependencies,
289 ffi_unwind_calls,
290 forbidden_lint_groups,
291 forgetting_copy_types,
292 forgetting_references,
293 for_loops_over_fallibles,
294 function_item_references,
295 hidden_glob_reexports,
296 improper_ctypes,
297 improper_ctypes_definitions,
298 inline_no_sanitize,
299 internal_features,
300 invalid_from_utf8,
301 invalid_macro_export_arguments,
302 invalid_nan_comparisons,
303 invalid_value,
304 irrefutable_let_patterns,
305 keyword_idents_2018,
306 keyword_idents_2024,
307 large_assignments,
308 late_bound_lifetime_arguments,
309 legacy_derive_helpers,
310 let_underscore_drop,
311 macro_use_extern_crate,
312 map_unit_fn,
313 meta_variable_misuse,
314 missing_abi,
315 missing_copy_implementations,
316 missing_debug_implementations,
317 missing_docs,
318 mixed_script_confusables,
319 named_arguments_used_positionally,
320 never_type_fallback_flowing_into_unsafe,
321 no_mangle_generic_items,
322 non_ascii_idents,
323 non_camel_case_types,
324 non_contiguous_range_endpoints,
325 non_fmt_panics,
326 non_local_definitions,
327 non_shorthand_field_patterns,
328 non_snake_case,
329 non_upper_case_globals,
330 noop_method_call,
331 opaque_hidden_inferred_bound,
332 overlapping_range_endpoints,
333 path_statements,
334 private_bounds,
335 private_interfaces,
336 redundant_lifetimes,
337 redundant_semicolons,
338 refining_impl_trait_internal,
339 refining_impl_trait_reachable,
340 renamed_and_removed_lints,
341 repr_transparent_external_private_fields,
342 rust_2021_incompatible_closure_captures,
343 rust_2021_incompatible_or_patterns,
344 rust_2021_prefixes_incompatible_syntax,
345 rust_2021_prelude_collisions,
346 semicolon_in_expressions_from_macros,
347 special_module_name,
348 stable_features,
349 static_mut_refs,
350 suspicious_double_ref_op,
351 trivial_bounds,
352 trivial_casts,
353 trivial_numeric_casts,
354 type_alias_bounds,
355 tyvar_behind_raw_pointer,
356 uncommon_codepoints,
357 unconditional_recursion,
358 uncovered_param_in_projection,
359 undefined_naked_function_abi,
360 ungated_async_fn_track_caller,
361 uninhabited_static,
362 unit_bindings,
363 unknown_lints,
364 unknown_or_malformed_diagnostic_attributes,
365 unnameable_test_items,
366 unnameable_types,
367 unreachable_code,
368 unreachable_patterns,
369 unreachable_pub,
370 unsafe_code,
371 unsafe_op_in_unsafe_fn,
372 unstable_name_collisions,
373 unstable_syntax_pre_expansion,
374 unused_allocation,
375 unused_assignments,
376 unused_associated_type_bounds,
377 unused_attributes,
378 unused_braces,
379 unused_comparisons,
380 unused_crate_dependencies,
381 unused_doc_comments,
382 unused_extern_crates,
383 unused_features,
384 unused_import_braces,
385 unused_imports,
386 unused_labels,
387 unused_lifetimes,
388 unused_macro_rules,
389 unused_macros,
390 unused_must_use,
391 unused_mut,
392 unused_parens,
393 unused_qualifications,
394 unused_results,
395 unused_unsafe,
396 unused_variables,
397 useless_ptr_null_checks,
398 variant_size_differences,
399 while_true,
400 )
401)]
402#![cfg_attr(all(nightly), allow(unstable_features))]
403// If nightly and unstable, allow `incomplete_features` and `unstable_features`
404#![cfg_attr(all(feature = "unstable", nightly), allow(incomplete_features))]
405// If nightly and not unstable, deny `incomplete_features` and `unstable_features`
406#![cfg_attr(
407 all(not(feature = "unstable"), nightly),
408 deny(incomplete_features, unstable_features)
409)]
410// The unstable lints
411#![cfg_attr(
412 all(feature = "unstable", nightly),
413 deny(
414 fuzzy_provenance_casts,
415 lossy_provenance_casts,
416 multiple_supertrait_upcastable,
417 must_not_suspend,
418 non_exhaustive_omitted_patterns,
419 unfulfilled_lint_expectations,
420 )
421)]
422// clippy lints
423#![cfg_attr(nightly, deny(clippy::all, clippy::pedantic))]
424// rustdoc lints
425#![cfg_attr(
426 nightly,
427 deny(
428 rustdoc::bare_urls,
429 rustdoc::broken_intra_doc_links,
430 rustdoc::invalid_codeblock_attributes,
431 rustdoc::invalid_html_tags,
432 rustdoc::missing_crate_level_docs,
433 rustdoc::private_doc_tests,
434 rustdoc::private_intra_doc_links,
435 )
436)]
437#![cfg_attr(
438 all(nightly, feature = "unstable"),
439 deny(rustdoc::missing_doc_code_examples)
440)]
441#![cfg_attr(all(doc, nightly), feature(doc_auto_cfg))]
442#![cfg_attr(all(docsrs, nightly), feature(doc_cfg))]
443#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
444
445mod git2;
446
447#[cfg(test)]
448use {lazy_static as _, regex as _, temp_env as _};
449// This is here to appease the `unused_crate_dependencies` lint
450#[cfg(not(any(
451 feature = "build",
452 feature = "cargo",
453 feature = "rustc",
454 feature = "si"
455)))]
456use vergen as _;
457
458pub use crate::git2::Git2;
459pub use crate::git2::Git2Builder;
460#[cfg(feature = "build")]
461pub use vergen::BuildBuilder;
462#[cfg(feature = "cargo")]
463pub use vergen::CargoBuilder;
464#[cfg(feature = "si")]
465pub use vergen::CpuRefreshKind;
466#[cfg(feature = "cargo")]
467pub use vergen::DependencyKind;
468#[cfg(feature = "si")]
469pub use vergen::MemoryRefreshKind;
470#[cfg(feature = "si")]
471pub use vergen::ProcessRefreshKind;
472#[cfg(feature = "si")]
473pub use vergen::RefreshKind;
474#[cfg(feature = "rustc")]
475pub use vergen::RustcBuilder;
476#[cfg(feature = "si")]
477pub use vergen::SysinfoBuilder;
478pub use vergen_lib::AddCustomEntries;
479pub use vergen_lib::CargoRerunIfChanged;
480pub use vergen_lib::CargoWarning;
481pub use vergen_lib::DefaultConfig;
482pub use vergen_lib::Emitter;