Struct debian_packaging::repository::builder::RepositoryBuilder

pub struct RepositoryBuilder<'cf> { /* private fields */ }

Build Debian repositories from scratch.

Instances of this type are used to iteratively construct a Debian repository.

A Debian repository consists of named components holding binary packages, sources, installer packages, and metadata gluing it all together.

Usage

Instances are constructed, preferably via Self::new_recommended().

Additional metadata about the repository is then registered using the following functions (as needed):

• Self::add_architecture()
• Self::add_component()
• Self::add_checksum()
• Self::set_suite()
• Self::set_codename()
• Self::set_date()
• Self::set_valid_until()
• Self::set_description()
• Self::set_origin()
• Self::set_label()
• Self::set_version()
• Self::set_acquire_by_hash()

See https://wiki.debian.org/DebianRepository/Format for a description of what these various fields are used for.

After basic metadata is in place, .deb packages are registered against the builder via Self::add_binary_deb().

Once everything is registered against the builder, it is time to publish (read: write) the repository content.

Publishing works by first writing pool content. The pool is an area of the repository where blobs (like .deb packages) are stored. To publish the pool, call Self::publish_pool_artifacts(). This takes a DataResolver for obtaining missing pool content. Its content retrieval functions will be called for each pool path that needs to be copied to the writer. Since crate::repository::RepositoryRootReader must implement DataResolver, you can pass an instance as the DataResolver to effectively copy artifacts from another Debian repository. Note: for this to work, the source repository must have the same PoolLayout as this repository. This may not always be the case! To more robustly copy files from another repository, instantiate a crate::io::PathMappingDataResolver and call crate::io::PathMappingDataResolver::add_path_map() with the result from Self::add_binary_deb() (and similar function) to install a path mapping.

Implementations

impl<'cf> RepositoryBuilder<'cf>

pub fn new_recommended_empty() -> Self

Create a new instance with recommended settings.

Files that should almost always be set (like Architectures and Components) are empty. It is recommended to use Self::new_recommended() instead.

pub fn new_recommended(
    architectures: impl Iterator<Item = impl ToString>,
    components: impl Iterator<Item = impl ToString>,
    suite: impl ToString,
    codename: impl ToString
) -> Self

Create a new instance with recommended settings and fields.

The arguments to this function are those that should be defined on most Debian repositories.

Calling this function is equivalent to calling Self::new_recommended_empty() then calling various .add_*() methods on the returned instance.

pub fn add_architecture(&mut self, arch: impl ToString)

Register an architecture with the builder.

This defines which platform architectures there will be packages for.

Example architecture values are all, amd64, arm64, and i386.

pub fn add_component(&mut self, name: impl ToString)

Register a named component with the builder.

Components describe a named subset of the repository. Example names include main, contrib, restricted, stable.

pub fn add_checksum(&mut self, value: ChecksumType)

Register a checksum type to emit.

ChecksumType::Sha256 should always be used. Adding ChecksumType::Md5 is recommended for compatibility with old clients.

pub fn set_suite(&mut self, value: impl ToString)

Set the Suite value.

This is often a value like stable, bionic, groovy. Some identifier that helps identify this repository.

pub fn set_codename(&mut self, value: impl ToString)

Set the Codename value.

This is often a human friendly name to help identify the repository. Example values include groovy, bullseye, bionic.

pub fn set_date(&mut self, value: DateTime<Utc>)

Set the time this repository was created/updated.

If not set, the current time will be used automatically.

pub fn set_valid_until(&mut self, value: DateTime<Utc>)

Set the value for the Valid-Until field.

Clients should not trust this repository after this date.

pub fn set_description(&mut self, value: impl ToString)

Set a human friendly description text for this repository.

pub fn set_origin(&mut self, value: impl ToString)

Set a field indicating the origin of the repository.

pub fn set_label(&mut self, value: impl ToString)

Set freeform text describing the repository.

pub fn set_version(&mut self, value: impl ToString)

Set the version of the release.

Typically . delimited integers.

pub fn set_acquire_by_hash(&mut self, value: bool)

Set the value of Acquire-By-Hash.

This should be enabled for new repositories.

pub fn set_pool_layout(&mut self, layout: PoolLayout) -> Result<()>

Set the PoolLayout to use.

The layout can only be updated before content is added. Once a package has been indexed, this function will error.

pub fn add_binary_deb(
    &mut self,
    component: &str,
    deb: &impl DebPackageReference<'cf>
) -> Result<String>

Add a binary package .deb to this repository in the given component.

The package to add is specified as a trait to enable callers to represent Debian packages differently. For example, the trait members may be implemented by just-in-time parsing of an actual .deb file or by retrieving the data from a cache.

The specified component name must be registered with this instance or an error will occur.

Returns the pool path / Filename field that this binary package .deb will occupy in the repository.

pub fn binary_package_components(
    &self
) -> impl Iterator<Item = (&str, &str)> + '_

Obtain all components having binary packages.

The iterator contains 2-tuples of (component, architecture).

pub fn iter_component_binary_packages(
    &self,
    component: impl ToString,
    architecture: impl ToString
) -> Box<dyn Iterator<Item = &ControlParagraph<'_>> + Send>

Obtain an iterator of ControlParagraph for binary packages in a given component + architecture.

This method forms the basic building block for constructing Packages files. Packages files can be built by serializing the ControlParagraph to a string/writer.

pub fn iter_component_binary_package_pool_artifacts(
    &self,
    component: impl ToString,
    architecture: impl ToString
) -> impl Iterator<Item = Result<BinaryPackagePoolArtifact<'_>>> + '_

Obtain an iterator of pool artifacts for binary packages that will need to exist.

pub fn component_binary_packages_reader(
    &self,
    component: impl ToString,
    architecture: impl ToString
) -> impl AsyncRead + '_

Obtain an [AsyncRead] that reads contents of a Packages file for binary packages.

This is a wrapper around Self::iter_component_binary_packages() that normalizes the ControlParagraph to data and converts it to an [AsyncRead].

pub fn component_binary_packages_reader_compression(
    &self,
    component: impl ToString,
    architecture: impl ToString,
    compression: Compression
) -> Pin<Box<dyn AsyncRead + Send>>

Like Self::component_binary_packages_reader() except data is compressed.

pub fn binary_packages_index_readers(
    &self
) -> impl Iterator<Item = IndexFileReader<'_>> + '_

Obtain IndexFileReader for each logical Packages file.

pub fn index_file_readers(
    &self
) -> impl Iterator<Item = IndexFileReader<'_>> + '_

Obtain all IndexFileReader to be published.

Each item corresponds to a logical item in an [In]Release.

pub fn iter_binary_packages_pool_artifacts(
    &self
) -> impl Iterator<Item = Result<BinaryPackagePoolArtifact<'_>>> + '_

Obtain records describing pool artifacts needed to support binary packages.

pub async fn publish_pool_artifacts<F>(
    &self,
    resolver: &impl DataResolver,
    writer: &impl RepositoryWriter,
    threads: usize,
    progress_cb: &Option<F>
) -> Result<()> where
    F: Fn(PublishEvent), 

Publish artifacts to the pool.

The pool is the area of a Debian repository holding files like the .deb packages.

Content must be published to the pool before indices data is written, otherwise there is a race condition where the indices could refer to files not yet in the pool.

pub fn create_release_file(
    &self,
    indices: impl Iterator<Item = (String, (u64, MultiContentDigest))>
) -> Result<ReleaseFile<'_>>

Derive a ReleaseFile representing the content of the Release file.

This takes an iterable describing indices files. This iterable is typically derived from Self::index_file_readers().

pub async fn publish_indices<F, PW>(
    &self,
    writer: &impl RepositoryWriter,
    path_prefix: Option<&str>,
    threads: usize,
    progress_cb: &Option<F>,
    signing_key: Option<(&impl SecretKeyTrait, PW)>
) -> Result<()> where
    F: Fn(PublishEvent),
    PW: FnOnce() -> String, 

Publish index files.

Repository index files describe the contents of the repository. Index files are referred to by the InRelease and Release files.

Indices should only be published after pool artifacts are published. Otherwise there is a race condition where an index file could refer to a file in the pool that does not exist.

pub async fn publish<F, PW>(
    &self,
    writer: &impl RepositoryWriter,
    resolver: &impl DataResolver,
    distribution_path: &str,
    threads: usize,
    progress_cb: &Option<F>,
    signing_key: Option<(&impl SecretKeyTrait, PW)>
) -> Result<()> where
    F: Fn(PublishEvent),
    PW: FnOnce() -> String, 

Publish the repository to the given RepositoryWriter.

This is the main function for writing out the desired state in this builder.

Publishing effectively works in 3 phases:

1. Publish missing pool artifacts.
2. Publish indices files (e.g. Packages lists).
3. Publish the InRelease and Release file.

writer is a RepositoryWriter used to perform I/O for writing output files. resolver is a DataResolver for resolving pool paths. It will be consulted to obtain paths of .deb and other pool files. distribution_path is the relative path under writer to write indices files under. It typically begins with dists/. e.g. dists/bullseye. This value becomes the directory with the generated InRelease file. threads is the number of parallel threads to use for I/O. progress_cb provides an optional function to receive progress updates. signing_key provides a signing key for PGP signing and an optional function to obtain the password to unlock that key.

Trait Implementations

impl<'cf> Debug for RepositoryBuilder<'cf>

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

Formats the value using the given formatter.

impl<'cf> Default for RepositoryBuilder<'cf>

fn default() -> RepositoryBuilder<'cf>

Returns the “default value” for a type.