Metadata in cargo::core::compiler::build_runner::compilation_files - Rust
Description: `Metadata` tracks several `UnitHash`s, including `Metadata::unit_id`, `Metadata::c_metadata`, and `Metadata::c_extra_filename`.

Skip to main content

## Metadata

# Struct Metadata

Source

    pub struct Metadata {
        unit_id: UnitHash,
        c_metadata: UnitHash,
        c_extra_filename: bool,
        pkg_dir: bool,
    }

Expand description

`Metadata` tracks several `UnitHash`s, including `Metadata::unit_id`, `Metadata::c_metadata`, and `Metadata::c_extra_filename`.

We use a hash because it is an easy way to guarantee that all the inputs can be converted to a valid path.

`Metadata::unit_id` is used to uniquely identify a unit in the build graph. This serves as a similar role as `Metadata::c_extra_filename` in that it uniquely identifies output on the filesystem except that its always present.

`Metadata::c_extra_filename` is needed for cases like:

- A project may depend on crate `A` and crate `B`, so the package name must be in the file name.
- Similarly a project may depend on two versions of `A`, so the version must be in the file name.

This also acts as the main layer of caching provided by Cargo so this must include all things that need to be distinguished in different parts of the same build. This is absolutely required or we override things before we get chance to use them.

For example, we want to cache `cargo build` and `cargo doc` separately, so that running one does not invalidate the artifacts for the other. We do this by including `CompileMode` in the hash, thus the artifacts go in different folders and do not override each other. If we don’t add something that we should have, for this reason, we get the correct output but rebuild more than is needed.

Some things that need to be tracked to ensure the correct output should definitely not go in the `Metadata`. For example, the modification time of a file, should be tracked to make a rebuild when the file changes. However, it would be wasteful to include in the `Metadata`. The old artifacts are never going to be needed again. We can save space by just overwriting them. If we add something that we should not have, for this reason, we get the correct output but take more space than needed. This makes not including something in `Metadata` a form of cache invalidation.

Note that the `Fingerprint` is in charge of tracking everything needed to determine if a rebuild is needed.

`Metadata::c_metadata` is used for symbol mangling, because if you have two versions of the same crate linked together, their symbols need to be differentiated.

You should avoid anything that would interfere with reproducible builds. For example, any absolute path should be avoided. This is one reason that `RUSTFLAGS` is not in `Metadata::c_metadata`, because it often has absolute paths (like `--remap-path-prefix` which is fundamentally used for reproducible builds and has absolute paths in it). Also, in some cases the mangled symbols need to be stable between different builds with different settings. For example, profile-guided optimizations need to swap `RUSTFLAGS` between runs, but needs to keep the same symbol names.

## Fields§

§`unit_id: UnitHash`§`c_metadata: UnitHash`§`c_extra_filename: bool`§`pkg_dir: bool`

## Implementations§

Source§

### impl Metadata

Source

#### pub fn unit_id(&self) -> UnitHash

A hash to identify a given `Unit` in the build graph

Source

#### pub fn c_metadata(&self) -> UnitHash

A hash to add to symbol naming through `-C metadata`

Source

#### pub fn c_extra_filename(&self) -> Option<UnitHash>

A hash to add to file names through `-C extra-filename`

Source

#### pub fn pkg_dir(&self) -> Option<UnitHash>

A hash to add to Cargo directory names

## Trait Implementations§

Source§

### impl Clone for Metadata

Source§

#### fn clone(&self) -> Metadata

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

#### fn clone_from(&mut self, source: &Self)

Performs copy-assignment from `source`. Read more
Source§

### impl Copy for Metadata

Source§

### impl Debug for Metadata

Source§

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

Formats the value using the given formatter. Read more

## Auto Trait Implementations§

§

### impl Freeze for Metadata

§

### impl RefUnwindSafe for Metadata

§

### impl Send for Metadata

§

### impl Sync for Metadata

§

### impl Unpin for Metadata

§

### impl UnsafeUnpin for Metadata

§

### impl UnwindSafe for Metadata

## Blanket Implementations§

Source§

### impl<T> Any for T
where T: 'static + ?Sized,

Source§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
Source§

### impl<T> Borrow<T> for T
where T: ?Sized,

Source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

### impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

### impl<T> CloneToUninit for T
where T: Clone,

Source§

#### unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (`clone_to_uninit`)
Performs copy-assignment from `self` to `dest`. Read more
Source§

### impl<T> From<T> for T

Source§

#### fn from(t: T) -> T

Returns the argument unchanged.

§

### impl<T> Instrument for T

§

#### fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [`Span`], returning an `Instrumented` wrapper. Read more
§

#### fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current `Span`, returning an `Instrumented` wrapper. Read more
Source§

### impl<T, U> Into<U> for T
where U: From<T>,

Source§

#### fn into(self) -> U

Calls `U::from(self)`.

That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.

Source§

### impl<T> IntoEither for T

Source§

#### fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts `self` into a `Left` variant of `Either<Self, Self>` if `into_left` is `true`. Converts `self` into a `Right` variant of `Either<Self, Self>` otherwise. Read more
Source§

#### fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts `self` into a `Left` variant of `Either<Self, Self>` if `into_left(&self)` returns `true`. Converts `self` into a `Right` variant of `Either<Self, Self>` otherwise. Read more
§

### impl<T> Pointable for T

§

#### const ALIGN: usize

The alignment of pointer.
§

#### type Init = T

The type for initializers.
§

#### unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

#### unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

#### unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

#### unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

### impl<T> Same for T

Source§

#### type Output = T

Should always be `Self`
Source§

### impl<T> ToOwned for T
where T: Clone,

Source§

#### type Owned = T

The resulting type after obtaining ownership.
Source§

#### fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

#### fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

### impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

#### type Error = Infallible

The type returned in the event of a conversion error.
Source§

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

### impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

### impl<T> WithSubscriber for T

§

#### fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided `Subscriber` to this type, returning a [`WithDispatch`] wrapper. Read more
§

#### fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default `Subscriber` to this type, returning a [`WithDispatch`] wrapper. Read more

## 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: 24 bytes