Skip to content

Commit 7900810

Browse files
epageepage
committed
docs(fingerprint): Track each use of Metadata separately
1 parent 65392dc commit 7900810

File tree

2 files changed

+40
-34
lines changed

2 files changed

+40
-34
lines changed

‎src/cargo/core/compiler/build_runner/compilation_files.rs

+4-4
Original file line numberDiff line numberDiff line change
@@ -41,18 +41,18 @@ impl fmt::Debug for UnitHash {
4141
}
4242
}
4343

44-
/// The `Metadata` is a hash used to make unique file names for each unit in a
45-
/// build. It is also used for symbol mangling.
44+
/// [`Metadata`] tracks several [`UnitHash`]s, including
45+
/// [`Metadata::unit_id`], [`Metadata::c_metadata`], and [`Metadata::c_extra_filename`].
4646
///
47-
/// For example:
47+
/// [`Metadata::c_extra_filename`] is needed for cases like:
4848
/// - A project may depend on crate `A` and crate `B`, so the package name must be in the file name.
4949
/// - Similarly a project may depend on two versions of `A`, so the version must be in the file name.
5050
///
5151
/// In general this must include all things that need to be distinguished in different parts of
5252
/// the same build. This is absolutely required or we override things before
5353
/// we get chance to use them.
5454
///
55-
/// It is also used for symbol mangling, because if you have two versions of
55+
/// [`Metadata::c_metadata`] is used for symbol mangling, because if you have two versions of
5656
/// the same crate linked together, their symbols need to be differentiated.
5757
///
5858
/// We use a hash because it is an easy way to guarantee

‎src/cargo/core/compiler/fingerprint/mod.rs

+36-30
Original file line numberDiff line numberDiff line change
@@ -47,46 +47,48 @@
4747
//! reliable and reproducible builds at the cost of being complex, slow, and
4848
//! platform-dependent.
4949
//!
50-
//! ## Fingerprints and Metadata
50+
//! ## Fingerprints and [`UnitHash`]s
51+
//!
52+
//! [`Metadata`] tracks several [`UnitHash`]s, including
53+
//! [`Metadata::unit_id`], [`Metadata::c_metadata`], and [`Metadata::c_extra_filename`].
54+
//! See its documentation for more details.
5155
//!
52-
//! The [`Metadata`] hash is a hash added to the output filenames to isolate
53-
//! each unit. See its documentationfor more details.
5456
//! NOTE: Not all output files are isolated via filename hashes (like dylibs).
5557
//! The fingerprint directory uses a hash, but sometimes units share the same
5658
//! fingerprint directory (when they don't have Metadata) so care should be
5759
//! taken to handle this!
5860
//!
59-
//! Fingerprints and Metadata are similar, and track some of the same things.
60-
//! The Metadata contains information that is required to keep Units separate.
61+
//! Fingerprints and [`UnitHash`]s are similar, and track some of the same things.
62+
//! [`UnitHash`]s contains information that is required to keep Units separate.
6163
//! The Fingerprint includes additional information that should cause a
6264
//! recompile, but it is desired to reuse the same filenames. A comparison
6365
//! of what is tracked:
6466
//!
65-
//! Value | Fingerprint | Metadata
66-
//! -------------------------------------------|-------------|----------
67-
//! rustc | ✓ | ✓
68-
//! [`Profile`] | ✓ | ✓
69-
//! `cargo rustc` extra args | ✓ | ✓
70-
//! [`CompileMode`] | ✓ | ✓
71-
//! Target Name | ✓ | ✓
72-
//! `TargetKind` (bin/lib/etc.) | ✓ | ✓
73-
//! Enabled Features | ✓ | ✓
74-
//! Declared Features | ✓ |
75-
//! Immediate dependency’s hashes | ✓[^1] | ✓
76-
//! [`CompileKind`] (host/target) | ✓ | ✓
77-
//! `__CARGO_DEFAULT_LIB_METADATA`[^4] | | ✓
78-
//! `package_id` | | ✓
79-
//! authors, description, homepage, repo | ✓ |
80-
//! Target src path relative to ws | ✓ |
81-
//! Target flags (test/bench/for_host/edition) | ✓ |
82-
//! -C incremental=… flag | ✓ |
83-
//! mtime of sources | ✓[^3] |
84-
//! RUSTFLAGS/RUSTDOCFLAGS | ✓ |
85-
//! [`Lto`] flags | ✓ | ✓
86-
//! config settings[^5] | ✓ |
87-
//! `is_std` | | ✓
88-
//! `[lints]` table[^6] | ✓ |
89-
//! `[lints.rust.unexpected_cfgs.check-cfg]` | ✓ |
67+
//! Value | Fingerprint | `Metadata::unit_id` | `Metadata::c_metadata` | `Metadata::c_extra_filename`
68+
//! -------------------------------------------|-------------|---------------------|------------------------|----------
69+
//! rustc | ✓ | ✓ | ✓ | ✓
70+
//! [`Profile`] | ✓ | ✓ | ✓ | ✓
71+
//! `cargo rustc` extra args | ✓ | ✓ | ✓ | ✓
72+
//! [`CompileMode`] | ✓ | ✓ | ✓ | ✓
73+
//! Target Name | ✓ | ✓ | ✓ | ✓
74+
//! `TargetKind` (bin/lib/etc.) | ✓ | ✓ | ✓ | ✓
75+
//! Enabled Features | ✓ | ✓ | ✓ | ✓
76+
//! Declared Features | ✓ | | |
77+
//! Immediate dependency’s hashes | ✓[^1] | ✓ | ✓ | ✓
78+
//! [`CompileKind`] (host/target) | ✓ | ✓ | ✓ | ✓
79+
//! `__CARGO_DEFAULT_LIB_METADATA`[^4] | | ✓ | ✓ | ✓
80+
//! `package_id` | | ✓ | ✓ | ✓
81+
//! authors, description, homepage, repo | ✓ | | |
82+
//! Target src path relative to ws | ✓ | | |
83+
//! Target flags (test/bench/for_host/edition) | ✓ | | |
84+
//! -C incremental=… flag | ✓ | | |
85+
//! mtime of sources | ✓[^3] | | |
86+
//! RUSTFLAGS/RUSTDOCFLAGS | ✓ | | |
87+
//! [`Lto`] flags | ✓ | ✓ | ✓ | ✓
88+
//! config settings[^5] | ✓ | | |
89+
//! `is_std` | | ✓ | ✓ | ✓
90+
//! `[lints]` table[^6] | ✓ | | |
91+
//! `[lints.rust.unexpected_cfgs.check-cfg]` | ✓ | | |
9092
//!
9193
//! [^1]: Build script and bin dependencies are not included.
9294
//!
@@ -348,6 +350,10 @@
348350
//!
349351
//! [`check_filesystem`]: Fingerprint::check_filesystem
350352
//! [`Metadata`]: crate::core::compiler::Metadata
353+
//! [`Metadata::unit_id`]: crate::core::compiler::Metadata::unit_id
354+
//! [`Metadata::c_metadata`]: crate::core::compiler::Metadata::c_metadata
355+
//! [`Metadata::c_extra_filename`]: crate::core::compiler::Metadata::c_extra_filename
356+
//! [`UnitHash`]: crate::core::compiler::UnitHash
351357
//! [`Profile`]: crate::core::profiles::Profile
352358
//! [`CompileMode`]: crate::core::compiler::CompileMode
353359
//! [`Lto`]: crate::core::compiler::Lto

0 commit comments

Comments
 (0)