Enum LocalFingerprint

enum LocalFingerprint {
    Precalculated(String),
    CheckDepInfo {
        dep_info: PathBuf,
        checksum: bool,
    },
    RerunIfChanged {
        output: PathBuf,
        paths: Vec<PathBuf>,
    },
    RerunIfEnvChanged {
        var: String,
        val: Option<String>,
    },
}

A LocalFingerprint represents something that we use to detect direct changes to a Fingerprint.

This is where we track file information, env vars, etc. This LocalFingerprint struct is hashed and if the hash changes will force a recompile of any fingerprint it’s included into. Note that the “local” terminology comes from the fact that it only has to do with one crate, and Fingerprint tracks the transitive propagation of fingerprint changes.

Note that because this is hashed its contents are carefully managed. Like mentioned in the above module docs, we don’t want to hash absolute paths or mtime information.

Also note that a LocalFingerprint is used in check_filesystem to detect when the filesystem contains stale information (based on mtime currently). The paths here don’t change much between compilations but they’re used as inputs when we probe the filesystem looking at information.

Variants

Precalculated(String)

This is a precalculated fingerprint which has an opaque string we just hash as usual. This variant is primarily used for rustdoc where we don’t have a dep-info file to compare against.

This is also used for build scripts with no rerun-if-* statements, but that’s overall a mistake and causes bugs in Cargo. We shouldn’t use this for build scripts.

CheckDepInfo

This is used for crate compilations. The dep_info file is a relative path anchored at target_root(...) to the dep-info file that Cargo generates (which is a custom serialization after parsing rustc’s own dep-info output).

The dep_info file, when present, also lists a number of other files for us to look at. If any of those files are newer than this file then we need to recompile.

If the checksum bool is true then the dep_info file is expected to contain file checksums instead of file mtimes.

Fields

dep_info: PathBuf

checksum: bool

RerunIfChanged

This represents a nonempty set of rerun-if-changed annotations printed out by a build script. The output file is a relative file anchored at target_root(...) which is the actual output of the build script. That output has already been parsed and the paths printed out via rerun-if-changed are listed in paths. The paths field is relative to pkg.root()

This is considered up-to-date if all of the paths are older than output, otherwise we need to recompile.

Fields

output: PathBuf

paths: Vec<PathBuf>

RerunIfEnvChanged

This represents a single rerun-if-env-changed annotation printed by a build script. The exact env var and value are hashed here. There’s no filesystem dependence here, and if the values are changed the hash will change forcing a recompile.

Fields

var: String

val: Option<String>

Implementations

impl LocalFingerprint

fn from_env<K: AsRef<str>>(key: K) -> LocalFingerprint

Read the environment variable of the given env key, and creates a new LocalFingerprint::RerunIfEnvChanged for it.

fn find_stale_item( &self, mtime_cache: &mut HashMap<PathBuf, FileTime>, checksum_cache: &mut HashMap<PathBuf, Checksum>, pkg_root: &Path, target_root: &Path, cargo_exe: &Path, gctx: &GlobalContext, ) -> CargoResult<Option<StaleItem>>

Checks dynamically at runtime if this LocalFingerprint has a stale item inside of it.

The main purpose of this function is to handle two different ways fingerprints can be invalidated:

• One is a dependency listed in rustc’s dep-info files is invalid. Note that these could either be env vars or files. We check both here.

• Another is the rerun-if-changed directive from build scripts. This is where we’ll find whether files have actually changed

fn kind(&self) -> &'static str

Trait Implementations

impl Debug for LocalFingerprint

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for LocalFingerprint

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Hash for LocalFingerprint

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Serialize for LocalFingerprint

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 56 bytes

Size for each variant:

• Precalculated: 31 bytes
• CheckDepInfo: 31 bytes
• RerunIfChanged: 55 bytes
• RerunIfEnvChanged: 55 bytes