Skip to main content

DirectorySource

Struct DirectorySource 

Source
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

Source

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.

Source

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.

Source

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.

Source

pub fn len(&self) -> usize

The number of entries walked, counting the root directory.

Source

pub fn is_empty(&self) -> bool

Whether the walk produced no entries.

Trait Implementations§

Source§

impl Source for DirectorySource

Source§

fn into_entries(self) -> Vec<SourceEntry>

Produce the entries, consuming the source.

Auto Trait Implementations§

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> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

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, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

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

fn try_from(value: U) -> Result<T, !>

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.