Struct Manifest

Source

pub struct Manifest { /* private fields */ }

Expand description

The record of one produced sysroot.

Implementations§

Source §

impl Manifest

Source

pub const fn new(target: TargetTuple) -> Self

An empty manifest for this target.

Source

pub const fn target(&self) -> TargetTuple

The target this sysroot is for.

Source

pub const fn kernel(&self) -> Option<Version>

The Linux release the kernel headers in this sysroot came out of, when one was recorded.

Absent has one meaning and it is not “nobody knows”: it is that this sysroot has no kernel headers in it. Every target that is not Linux is in that case, and so is a Linux sysroot produced before a kernel tree was installed beside it, which is a state the producer allows because the two trees are two commands. That is the one thing an optional line can mean here and it is why this one is optional where the provenance field is not: a file with no kernel headers in it has no kernel version, and an input always came from somewhere.

What it is for is the question somebody asks after a cross build read a header nobody expected. -print-sysroot answers where and the manifest answers what, and a sysroot whose record names the release its linux/ headers came out of makes a stale pairing visible instead of leaving it to be guessed at. Nothing here checks the version against the headers themselves, which is tamnd/rucc#925’s argument applied to the kernel tree rather than to glibc.

Source

pub const fn set_kernel(&mut self, version: Version)

Record which Linux release the kernel headers came out of.

Infallible, and in particular it does not refuse a target that has no kernel headers. The property this type owes its callers is that Manifest::parse reads back what Manifest::render wrote, so the reader accepts every manifest a producer can build and a kernel line on a Windows sysroot is a bug in the producer rather than a corrupt file.

Source

pub fn inputs(&self) -> &[Input]

Every input, in the order they were added.

Source

pub fn push(&mut self, input: Input)

Record one input.

Source

pub fn redistributable(&self) -> bool

Whether an artifact containing this whole sysroot can be published.

One input under a licence that says no makes the answer no, which is the only reading of a licence wall that is worth anything.

Source

pub fn sources(&self) -> Vec<&str>

Every distinct source in the manifest, sorted.

What a person asks first when two manifests differ, and what a licence notice is generated from.

Source

pub fn render(&self) -> String

The manifest as text, sorted by path.

The sort is what makes two runs comparable. A directory walk returns files in whatever order the filesystem keeps them, which differs between ext4 and APFS and sometimes between two runs on one of them, and a manifest that carried that order would report a difference between two identical sysroots.

Source

pub fn digest(&self) -> String

One number naming everything this sysroot is made of: the sha256 of Manifest::render, as sixty four lowercase hex characters.

The same number sha256sum prints for the manifest file itself, which is the property worth having. Whoever is handed a digest can check it with a tool they already have, and a digest that only our own code could compute would be a claim nobody can audit.

§What it is for

spec/cross-compile/13-distribution.md section 13.2 asks for the hash of a cache directory’s contents in the directory’s name, and a name cannot carry one: the path has to be computable before anything has been read, by the producer that is about to write the files and by the compiler that is about to read them, and neither of them has the contents when it asks. What the rule wanted is a way to say in one line what is under a directory, and this is that line. Two hosts producing a sysroot for one target compare a digest instead of a few thousand files, and a digest published with a release can be held against a directory on a machine.

§What it covers

What the manifest covers, which is every file in the sysroot and the Linux release its kernel headers came out of. Not the kernel tree’s own files, because they are not in the sysroot: one tree serves every Linux target, so it sits in the cache beside the sysroots and crate::Manifest::kernel is what a sysroot says about it.

It is a fact about the target and its inputs rather than about the host, because the render is sorted, holds no absolute path and holds no timestamp. That is the same argument spec/cross-compile/02-the-goal.md claim 5 rests on, applied to the record rather than to the output.

Source

pub fn parse(text: &str) -> Result<Self, ManifestError>

Read a manifest back.

§Errors

Returns which line was wrong and what was wrong with it. A manifest that fails to parse is a cache entry somebody has to decide about, and “invalid manifest” is not enough to decide with.