vergen/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 - Emit cargo instructions from a build script
10//! `vergen`, when used in conjunction with cargo [build scripts] can emit the following:
11//!
12//! - Will emit [`cargo:rustc-env=VAR=VALUE`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#cargorustc-envvarvalue)
13//! 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.
14//! - Can emit [`cargo:warning`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#cargo-warning) outputs if the
15//! [`fail_on_error`](Emitter::fail_on_error) feature is not enabled and the requested variable is defaulted through error or
16//! the [`idempotent`](Emitter::idempotent) flag.
17//! - Will emit [`cargo:rerun-if-changed=build.rs`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed)
18//! to rerun instruction emission if the `build.rs` file changed.
19//! - Will emit [`cargo:rerun-if-env-changed=VERGEN_IDEMPOTENT`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed)
20//! to rerun instruction emission if the `VERGEN_IDEMPOTENT` environment variable has changed.
21//! - Will emit [`cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed)
22//! to rerun instruction emission if the `SOURCE_DATE_EPOCH` environment variable has changed.
23//! - Will emit custom instructions via the [`AddCustomEntries`] and the [`add_custom_instructions`](Emitter::add_custom_instructions) function.
24//!
25//! ## Usage
26//!
27//! 1. Ensure you have build scripts enabled via the `build` configuration in your `Cargo.toml`
28//!
29//! ```toml
30//! [package]
31//! #..
32//! build = "build.rs"
33//! ```
34//!
35//! 2. Add `vergen` as a build dependency in `Cargo.toml`, specifying the features you wish to enable.
36//!
37//! ```toml
38//! [dependencies]
39//! #..
40//!
41//! [build-dependencies]
42//! # All features enabled
43//! vergen = { version = "9.0.0", features = ["build", "cargo", "rustc", "si"] }
44//! # or
45//! vergen = { version = "9.0.0", features = ["build"] }
46//! # if you wish to disable certain features
47//! ```
48//!
49//! 3. Create a `build.rs` file that uses `vergen` to emit cargo instructions. Configuration
50//! starts with [`Emitter`]. Eventually you will call [`emit`](Emitter::emit) to output the
51//! cargo instructions. See the [`emit`](Emitter::emit) documentation for more robust examples.
52//!
53//! #### Generate all output
54//!
55//! ```
56//! # use anyhow::Result;
57//! # use vergen::Emitter;
58#![cfg_attr(feature = "build", doc = r"# use vergen::BuildBuilder;")]
59#![cfg_attr(feature = "cargo", doc = r"# use vergen::CargoBuilder;")]
60#![cfg_attr(feature = "rustc", doc = r"# use vergen::RustcBuilder;")]
61#![cfg_attr(feature = "si", doc = r"# use vergen::SysinfoBuilder;")]
62#![cfg_attr(feature = "cargo", doc = r"# use test_util::with_cargo_vars;")]
63//! #
64//! # pub fn main() -> Result<()> {
65#![cfg_attr(feature = "cargo", doc = r"# let result = with_cargo_vars(|| {")]
66//! // NOTE: This will output everything, and requires all features enabled.
67//! // NOTE: See the specific builder documentation for configuration options.
68#![cfg_attr(feature = "build", doc = r"let build = BuildBuilder::all_build()?;")]
69#![cfg_attr(feature = "cargo", doc = r"let cargo = CargoBuilder::all_cargo()?;")]
70#![cfg_attr(feature = "rustc", doc = r"let rustc = RustcBuilder::all_rustc()?;")]
71#![cfg_attr(feature = "si", doc = r"let si = SysinfoBuilder::all_sysinfo()?;")]
72//!
73//! Emitter::default()
74#![cfg_attr(feature = "build", doc = r" .add_instructions(&build)?")]
75#![cfg_attr(feature = "cargo", doc = r" .add_instructions(&cargo)?")]
76#![cfg_attr(feature = "rustc", doc = r" .add_instructions(&rustc)?")]
77#![cfg_attr(feature = "si", doc = r" .add_instructions(&si)?")]
78//! .emit()?;
79#![cfg_attr(
80 feature = "cargo",
81 doc = r"
82# Ok(())
83# });
84# assert!(result.is_ok());"
85)]
86//! # Ok(())
87//! # }
88//! ```
89//! #### Sample Output
90//! ```text
91//! cargo:rustc-env=VERGEN_BUILD_DATE=2024-01-31
92//! cargo:rustc-env=VERGEN_BUILD_TIMESTAMP=2024-01-31T03:26:34.065893658Z
93//! cargo:rustc-env=VERGEN_CARGO_DEBUG=true
94//! cargo:rustc-env=VERGEN_CARGO_FEATURES=
95//! cargo:rustc-env=VERGEN_CARGO_OPT_LEVEL=0
96//! cargo:rustc-env=VERGEN_CARGO_TARGET_TRIPLE=x86_64-unknown-linux-gnu
97//! cargo:rustc-env=VERGEN_CARGO_DEPENDENCIES=anyhow 1.0.79,vergen-pretty 0.3.2
98//! cargo:rustc-env=VERGEN_RUSTC_CHANNEL=nightly
99//! cargo:rustc-env=VERGEN_RUSTC_COMMIT_DATE=2024-01-29
100//! cargo:rustc-env=VERGEN_RUSTC_COMMIT_HASH=5518eaa946291f00471af8b254b2a1715f234882
101//! cargo:rustc-env=VERGEN_RUSTC_HOST_TRIPLE=x86_64-unknown-linux-gnu
102//! cargo:rustc-env=VERGEN_RUSTC_LLVM_VERSION=17.0
103//! cargo:rustc-env=VERGEN_RUSTC_SEMVER=1.77.0-nightly
104//! cargo:rustc-env=VERGEN_SYSINFO_NAME=Arch Linux
105//! cargo:rustc-env=VERGEN_SYSINFO_OS_VERSION=Linux Arch Linux
106//! cargo:rustc-env=VERGEN_SYSINFO_USER=jozias
107//! cargo:rustc-env=VERGEN_SYSINFO_TOTAL_MEMORY=31 GiB
108//! cargo:rustc-env=VERGEN_SYSINFO_CPU_VENDOR=AuthenticAMD
109//! cargo:rustc-env=VERGEN_SYSINFO_CPU_CORE_COUNT=8
110//! cargo:rustc-env=VERGEN_SYSINFO_CPU_NAME=cpu0,cpu1,cpu2,cpu3,cpu4,cpu5,cpu6,cpu7
111//! cargo:rustc-env=VERGEN_SYSINFO_CPU_BRAND=AMD Ryzen Threadripper 1900X 8-Core Processor
112//! cargo:rustc-env=VERGEN_SYSINFO_CPU_FREQUENCY=3792
113//! cargo:rerun-if-changed=build.rs
114//! cargo:rerun-if-env-changed=VERGEN_IDEMPOTENT
115//! cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH
116//! ```
117//!
118//! #### Generate specific output
119//!
120//! ```
121//! # use anyhow::Result;
122//! # use vergen::Emitter;
123#![cfg_attr(feature = "build", doc = r"# use vergen::BuildBuilder;")]
124#![cfg_attr(feature = "cargo", doc = r"# use vergen::CargoBuilder;")]
125#![cfg_attr(feature = "rustc", doc = r"# use vergen::RustcBuilder;")]
126#![cfg_attr(feature = "si", doc = r"# use vergen::SysinfoBuilder;")]
127#![cfg_attr(feature = "cargo", doc = r"# use test_util::with_cargo_vars;")]
128//! #
129//! # pub fn main() -> Result<()> {
130#![cfg_attr(feature = "cargo", doc = r"# let result = with_cargo_vars(|| {")]
131#![cfg_attr(
132 feature = "build",
133 doc = r"// NOTE: This will output only the instructions specified.
134// NOTE: See the specific builder documentation for configuration options.
135let build = BuildBuilder::default().build_timestamp(true).build()?;"
136)]
137#![cfg_attr(
138 feature = "cargo",
139 doc = r"let cargo = CargoBuilder::default().opt_level(true).build()?;"
140)]
141#![cfg_attr(
142 feature = "rustc",
143 doc = r"let rustc = RustcBuilder::default().semver(true).build()?;"
144)]
145#![cfg_attr(
146 feature = "si",
147 doc = r"let si = SysinfoBuilder::default().cpu_core_count(true).build()?;"
148)]
149//!
150//! Emitter::default()
151#![cfg_attr(feature = "build", doc = r" .add_instructions(&build)?")]
152#![cfg_attr(feature = "cargo", doc = r" .add_instructions(&cargo)?")]
153#![cfg_attr(feature = "rustc", doc = r" .add_instructions(&rustc)?")]
154#![cfg_attr(feature = "si", doc = r" .add_instructions(&si)?")]
155//! .emit()?;
156#![cfg_attr(
157 feature = "cargo",
158 doc = r"
159# Ok(())
160# });
161# assert!(result.is_ok());"
162)]
163//! # Ok(())
164//! # }
165//! ```
166//! #### Sample Output
167//! ```text
168//! cargo:rustc-env=VERGEN_BUILD_TIMESTAMP=2024-01-31T03:26:34.065893658Z
169//! cargo:rustc-env=VERGEN_CARGO_OPT_LEVEL=0
170//! cargo:rustc-env=VERGEN_RUSTC_SEMVER=1.77.0-nightly
171//! cargo:rustc-env=VERGEN_SYSINFO_CPU_CORE_COUNT=8
172//! cargo:rerun-if-changed=build.rs
173//! cargo:rerun-if-env-changed=VERGEN_IDEMPOTENT
174//! cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH
175//! ```
176//!
177//! 4. Use the [`env!`](std::env!) or [`option_env!`](std::option_env!) macro in your code to read the environment variables.
178//!
179//! ```
180//! if let Some(timestamp) = option_env!("VERGEN_BUILD_TIMESTAMP") {
181//! println!("Build Timestamp: {timestamp}");
182//! }
183//! if let Some(describe) = option_env!("VERGEN_GIT_DESCRIBE") {
184//! println!("git describe: {describe}");
185//! }
186//! ```
187//!
188//! ## Features
189//! `vergen` has four main feature toggles allowing you to customize your output. No features are enabled by default.
190//! You **must** specifically enable the features you wish to use.
191# function. This version of emit will also set the instructions you requests as environment variables for use in `build.rs`"
194)]
195//!
196//! | Feature | Enables |
197//! | ------------ | ----------------------------- |
198//! | build | `VERGEN_BUILD_*` instructions |
199//! | cargo | `VERGEN_CARGO_*` instructions |
200//! | rustc | `VERGEN_RUSTC_*` instructions |
201//! | si | `VERGEN_SYSINFO_*` instructions |
202# function |"
205)]
206//!
207//! ## Environment Variables
208//! `vergen` currently recognizes the following environment variables. The full list of the environment variable names can be
209//! found as [constants here](https://docs.rs/vergen-lib/latest/vergen_lib/constants/features/index.html)
210//!
211//! | Variable | Functionality |
212//! | -------- | ------------- |
213//! | `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. |
214//! | `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. |
215//! | `VERGEN_BUILD_*` | If this environment variable is set `vergen` will use the value you specify for the output rather than generating it. |
216//! | `VERGEN_CARGO_*` | If this environment variable is set `vergen` will use the value you specify for the output rather than generating it. |
217//! | `VERGEN_RUSTC_*` | If this environment variable is set `vergen` will use the value you specify for the output rather than generating it. |
218//! | `VERGEN_SYSINFO_*` | If this environment variable is set `vergen` will use the value you specify for the output rather than generating it. |
219//!
220//! ## Goals
221//! I initially wrote `vergen` (**ver**sion **gen**erator, so original) so I could embed a some git information in my
222//! personal projects. Now, usage has grown to the point that `vergen` needs to fit better in the rust ecosystem.
223//!
224//! The current goals are as follows:
225//!
226//! #### Minimize the tool footprint
227//! - Adopt an opt-in, rather than opt-out strategy for the features. The default feature set is empty
228//! and no instructions will be emitted.
229//! - The instructions you have configured **will** be emitted. If there are errors or idempotentcy
230//! has been configured, some of those instructions may be defaulted.
231//! - Allow overriding configurtion set in `build.rs` through environment variables. This will allow package
232//! maintainers to force sane defaults when packaging rust binaries for distribution.
233//!
234//! #### Minimize the compile time impact
235//! - I've removed some extraneous libraries. Any libraries added in the future will be checked against
236//! the current standard compile times to ensure the impact is not too great.
237//! - `vergen` should compile and test from a source tarball.
238//!
239//! #### Support deterministic output
240//! Compilations run from the same source oftentimes need to generate identical binaries. `vergen` now supports
241//! this determinism in a few ways.
242//! - An [`idempotent`](Emitter::idempotent) configuration option has been added. When this is enabled in a
243//! build script, each build via cargo against the same source code should generate identical binaries. Instructions
244//! that output information that may change between builds (i.e. timestamps, sysinfo) will be defaulted.
245//! - Recognize common environment variables that support deterministic builds (i.e. [`SOURCE_DATE_EPOCH`](https://reproducible-builds.org/docs/source-date-epoch/))
246//! - Allow `build.rs` configuration overrides though environment variables to allow users building a binary, but
247//! not controlling the source to generate deterministic binaries.
248//!
249//! # Use Cases
250//! I generally use vergen for the following two cases
251//!
252//! 1. Generating verbose output describing a command line application.
253//!
254//! ```text
255//! ~/p/r/app λ app -vv
256//! app 0.1.0
257//!
258//! Build Timestamp: 2021-02-23T20:14:46.558472672+00:00
259//! rustc Version: 1.52.0-nightly
260//! rustc Channel: nightly
261//! rustc Host Triple: x86_64-unknown-linux-gnu
262//! rustc Commit SHA: 3f5aee2d5241139d808f4fdece0026603489afd1
263//! cargo Target Triple: x86_64-unknown-linux-musl
264//! cargo Profile: release
265//! ```
266//!
267//! 2. Information endpoints in web apis
268//!
269//! ```json
270//! ~/p/r/app λ curl https://some.app.com/info | jq
271//! {
272//! "build_timestamp": "2021-02-19T21:32:22.932833758+00:00",
273//! "rustc_semver": "1.52.0-nightly",
274//! "rustc_channel": "nightly",
275//! "rustc_host_triple": "x86_64-unknown-linux-gnu",
276//! "rustc_commit_sha": "3f5aee2d5241139d808f4fdece0026603489afd1",
277//! "cargo_target_triple": "x86_64-unknown-linux-musl",
278//! "cargo_profile": "release"
279//! }
280//! ```
281//!
282//! [build scripts]: https://doc.rust-lang.org/cargo/reference/build-scripts.html#outputs-of-the-build-script
283//! [cargo:rustc-env]: https://doc.rust-lang.org/cargo/reference/build-scripts.html#rustc-env
284//! [cargo:rerun-if-changed]: https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed
285//!
286
287// rustc lints
288#![cfg_attr(
289 all(feature = "unstable", nightly),
290 feature(
291 multiple_supertrait_upcastable,
292 must_not_suspend,
293 non_exhaustive_omitted_patterns_lint,
294 rustdoc_missing_doc_code_examples,
295 strict_provenance_lints,
296 )
297)]
298#![cfg_attr(nightly, allow(single_use_lifetimes, unexpected_cfgs))]
299#![cfg_attr(
300 nightly,
301 deny(
302 absolute_paths_not_starting_with_crate,
303 ambiguous_glob_imports,
304 ambiguous_glob_reexports,
305 ambiguous_wide_pointer_comparisons,
306 anonymous_parameters,
307 array_into_iter,
308 asm_sub_register,
309 async_fn_in_trait,
310 bad_asm_style,
311 bare_trait_objects,
312 break_with_label_and_loop,
313 clashing_extern_declarations,
314 coherence_leak_check,
315 confusable_idents,
316 const_evaluatable_unchecked,
317 const_item_mutation,
318 dangling_pointers_from_temporaries,
319 dead_code,
320 deprecated,
321 deprecated_in_future,
322 deprecated_where_clause_location,
323 deref_into_dyn_supertrait,
324 deref_nullptr,
325 drop_bounds,
326 dropping_copy_types,
327 dropping_references,
328 duplicate_macro_attributes,
329 dyn_drop,
330 elided_lifetimes_in_associated_constant,
331 elided_lifetimes_in_paths,
332 ellipsis_inclusive_range_patterns,
333 explicit_outlives_requirements,
334 exported_private_dependencies,
335 ffi_unwind_calls,
336 forbidden_lint_groups,
337 forgetting_copy_types,
338 forgetting_references,
339 for_loops_over_fallibles,
340 function_item_references,
341 hidden_glob_reexports,
342 improper_ctypes,
343 improper_ctypes_definitions,
344 inline_no_sanitize,
345 internal_features,
346 invalid_from_utf8,
347 invalid_macro_export_arguments,
348 invalid_nan_comparisons,
349 invalid_value,
350 irrefutable_let_patterns,
351 keyword_idents_2018,
352 keyword_idents_2024,
353 large_assignments,
354 late_bound_lifetime_arguments,
355 legacy_derive_helpers,
356 let_underscore_drop,
357 macro_use_extern_crate,
358 map_unit_fn,
359 meta_variable_misuse,
360 missing_abi,
361 missing_copy_implementations,
362 missing_debug_implementations,
363 missing_docs,
364 mixed_script_confusables,
365 named_arguments_used_positionally,
366 never_type_fallback_flowing_into_unsafe,
367 no_mangle_generic_items,
368 non_ascii_idents,
369 non_camel_case_types,
370 non_contiguous_range_endpoints,
371 non_fmt_panics,
372 non_local_definitions,
373 non_shorthand_field_patterns,
374 non_snake_case,
375 non_upper_case_globals,
376 noop_method_call,
377 opaque_hidden_inferred_bound,
378 overlapping_range_endpoints,
379 path_statements,
380 private_bounds,
381 private_interfaces,
382 redundant_lifetimes,
383 redundant_semicolons,
384 refining_impl_trait_internal,
385 refining_impl_trait_reachable,
386 renamed_and_removed_lints,
387 repr_transparent_external_private_fields,
388 rust_2021_incompatible_closure_captures,
389 rust_2021_incompatible_or_patterns,
390 rust_2021_prefixes_incompatible_syntax,
391 rust_2021_prelude_collisions,
392 semicolon_in_expressions_from_macros,
393 special_module_name,
394 stable_features,
395 static_mut_refs,
396 suspicious_double_ref_op,
397 trivial_bounds,
398 trivial_casts,
399 trivial_numeric_casts,
400 type_alias_bounds,
401 tyvar_behind_raw_pointer,
402 uncommon_codepoints,
403 unconditional_recursion,
404 uncovered_param_in_projection,
405 undefined_naked_function_abi,
406 ungated_async_fn_track_caller,
407 uninhabited_static,
408 unit_bindings,
409 unknown_lints,
410 unknown_or_malformed_diagnostic_attributes,
411 unnameable_test_items,
412 unnameable_types,
413 unreachable_code,
414 unreachable_patterns,
415 unreachable_pub,
416 unsafe_code,
417 unsafe_op_in_unsafe_fn,
418 unstable_name_collisions,
419 unstable_syntax_pre_expansion,
420 unused_allocation,
421 unused_assignments,
422 unused_associated_type_bounds,
423 unused_attributes,
424 unused_braces,
425 unused_comparisons,
426 unused_crate_dependencies,
427 unused_doc_comments,
428 unused_extern_crates,
429 unused_features,
430 unused_import_braces,
431 unused_imports,
432 unused_labels,
433 unused_lifetimes,
434 unused_macro_rules,
435 unused_macros,
436 unused_must_use,
437 unused_mut,
438 unused_parens,
439 unused_qualifications,
440 unused_results,
441 unused_unsafe,
442 unused_variables,
443 useless_ptr_null_checks,
444 variant_size_differences,
445 wasm_c_abi,
446 while_true,
447 )
448)]
449#![cfg_attr(all(nightly), allow(unstable_features))]
450// If nightly and unstable, allow `incomplete_features` and `unstable_features`
451#![cfg_attr(all(feature = "unstable", nightly), allow(incomplete_features))]
452// If nightly and not unstable, deny `incomplete_features` and `unstable_features`
453#![cfg_attr(
454 all(not(feature = "unstable"), nightly),
455 deny(incomplete_features, unstable_features)
456)]
457// The unstable lints
458#![cfg_attr(
459 all(feature = "unstable", nightly),
460 deny(
461 fuzzy_provenance_casts,
462 lossy_provenance_casts,
463 multiple_supertrait_upcastable,
464 must_not_suspend,
465 non_exhaustive_omitted_patterns,
466 unfulfilled_lint_expectations,
467 )
468)]
469// clippy lints
470#![cfg_attr(nightly, deny(clippy::all, clippy::pedantic))]
471// rustdoc lints
472#![cfg_attr(
473 nightly,
474 deny(
475 rustdoc::bare_urls,
476 rustdoc::broken_intra_doc_links,
477 rustdoc::invalid_codeblock_attributes,
478 rustdoc::invalid_html_tags,
479 rustdoc::missing_crate_level_docs,
480 rustdoc::private_doc_tests,
481 rustdoc::private_intra_doc_links,
482 )
483)]
484#![cfg_attr(
485 all(nightly, feature = "unstable"),
486 deny(rustdoc::missing_doc_code_examples)
487)]
488#![cfg_attr(all(doc, nightly), feature(doc_auto_cfg))]
489#![cfg_attr(all(docsrs, nightly), feature(doc_cfg))]
490#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
491
492mod feature;
493
494// This is here to appease the `unused_crate_dependencies` lint
495#[cfg(not(any(
496 feature = "build",
497 feature = "cargo",
498 feature = "rustc",
499 feature = "si"
500)))]
501use {anyhow as _, derive_builder as _};
502#[cfg(test)]
503use {lazy_static as _, regex as _, serial_test as _, temp_env as _, test_util as _};
504
505#[cfg(feature = "cargo")]
506pub use cargo_metadata::DependencyKind;
507#[cfg(feature = "build")]
508pub use feature::build::Build;
509#[cfg(feature = "build")]
510pub use feature::build::BuildBuilder;
511#[cfg(feature = "cargo")]
512pub use feature::cargo::Cargo;
513#[cfg(feature = "cargo")]
514pub use feature::cargo::CargoBuilder;
515#[cfg(feature = "rustc")]
516pub use feature::rustc::Rustc;
517#[cfg(feature = "rustc")]
518pub use feature::rustc::RustcBuilder;
519#[cfg(feature = "si")]
520pub use feature::si::Sysinfo;
521#[cfg(feature = "si")]
522pub use feature::si::SysinfoBuilder;
523#[cfg(feature = "si")]
524pub use sysinfo::CpuRefreshKind;
525#[cfg(feature = "si")]
526pub use sysinfo::MemoryRefreshKind;
527#[cfg(feature = "si")]
528pub use sysinfo::ProcessRefreshKind;
529#[cfg(feature = "si")]
530pub use sysinfo::RefreshKind;
531pub use vergen_lib::AddCustomEntries;
532pub use vergen_lib::CargoRerunIfChanged;
533pub use vergen_lib::CargoWarning;
534pub use vergen_lib::DefaultConfig;
535pub use vergen_lib::Emitter;