pub struct DirectorySource { /* private fields */ }Expand description
A Source that yields the entries walked from a directory on the host.
The directory itself becomes the filesystem root: its mode, ownership, times, and extended attributes are the root directory’s, and everything under it keeps its path relative to it.
§Example
use ferrosys::{DirectorySource, Timestamp};
use ferrosys::ext::{FormatOptions, format_to};
let time = Timestamp::from_secs(1_700_000_000);
// A build running as an ordinary user wants the image owned by root, not by itself.
let source = DirectorySource::from_path("staging/rootfs")?.owner(0, 0);
let mut out = std::fs::File::create("rootfs.img")?;
format_to(source, 512 << 20, FormatOptions::new([0x11; 16], time, [0; 16]), &mut out)?;Implementations§
Source§impl DirectorySource
impl DirectorySource
Sourcepub fn from_path(root: impl AsRef<Path>) -> Result<Self, HostError>
pub fn from_path(root: impl AsRef<Path>) -> Result<Self, HostError>
Walk the directory tree at root into a source.
Symlinks are recorded as symlinks and never followed, so a link pointing outside
the tree is written as the link it is — and that holds of what the format reads as
well as of what the walk records. Every directory is listed through a handle opened
beneath its parent’s without following a link, and a file’s bytes are read at
placement from the root’s handle one name at a time, following nothing, and only from
the file the walk recorded. A local writer replacing a staged file, or any directory
above it, with a link between the walk and the placement gets an error rather than
the target’s bytes in the image. Every directory below root is descended,
including one on another mounted filesystem — but each is descended once: two paths
naming a single directory, which a bind mount produces, is
HostError::RepeatedDirectory rather than a second copy of that subtree in the
image or, where what is mounted is an ancestor, a walk with no end.
§Errors
A HostError if root is not a directory, if any path under it cannot be read,
if a stored ACL cannot be translated, if one directory is reached by two paths, or if
a name is replaced while it is walked.
Sourcepub fn owner(self, uid: u32, gid: u32) -> Self
pub fn owner(self, uid: u32, gid: u32) -> Self
Replace every entry’s ownership with uid and gid.
A walk records what the host files carry, which for a build running as an ordinary
user is that user’s own ids. owner(0, 0) is what makes such a build produce the
root-owned image it means to.
Sourcepub fn times_from_modification(self) -> Self
pub fn times_from_modification(self) -> Self
Replace every entry’s access and change times with its own modification time.
A walk records all three times the host carries, and two of them move under the host’s feet. Reading a file updates its access time, so a build that reads the tree is itself enough to change what the next walk records; the change time moves whenever anything sets a mode, an owner, or a link count, which is what staging a tree does. The modification time moves only when a file’s contents do, so it is the one that describes the tree rather than the history of the machine holding it.
This makes a walked entry’s times what Metadata::new gives for that entry’s
modification time, so one tree walks to one image however many times it has been
read or restaged. It is the clamp for a build that needs reproducible bytes and
keeps per-file modification times; a family’s own fixed_time is the clamp for one
that forces every inode to a single time instead.
The creation time is derived from the modification time by the model, so it follows without being named here.