Struct rust_release_artefact::ExtractedArtefact

pub struct ExtractedArtefact {
    pub version: String,
    pub git_commit_hash: Option<String>,
    pub components: BTreeMap<String, Component>,
}

The metadata and content of a previously-extracted artefact.

Once you've downloaded a Rust release artefact, you must extract it to a staging area to examine it or install it. Use the from_tar_gz() or from_tar_xz() methods (whichever is appropriate) to extract your artefact. You may use a temporary directory as the staging area, or (if you might want to work with the same artefact again later) use a more permanent directory and call the new() method in future.

When an ExtractedArtefact struct is created, all of the artefact metadata is read into memory, so it's still usable if the staging area is removed. However, this does not include the artefact data, so if you want to call Component::install_to() you'll need to keep the staging area around at least that long.

Example

See Read artefact metadata in the crate-wide documentation.

Fields

version: String

The version of the package that was built to produce this artefact.

This should be a SemVer version number of the form X.Y.Z, followed by a space, an open-parenthesis, a Git commit ID truncated to 9 digits, a space, the date of that commit in YYYY-MM-DD format, and a close-parenthesis: 1.2.3 (a1b2c3d4e 2018-04-17)

git_commit_hash: Option<String>

The complete Git commit ID of this version of this package.

Not every artefact includes a commit ID.

components: BTreeMap<String, Component>

A mapping from component names to the files each component contains.

An artefact must contain at least one component, and may contain more.

Methods

impl ExtractedArtefact

pub fn new<P: AsRef<Path>>(stage: P) -> Result<ExtractedArtefact, Error>

Read previously-extracted artefact metadata.

stage must be the path to a directory containing an extracted artefact, such as one populated by the from_tar_gz() or from_tar_xz() methods.

Errors

This method may return any variant of Error.

The staging area will not be modfied, even if an error is returned.

Portability

Rust release artefacts may include a deeply-nested directory structure, which can exceed Windows' traditional 260 character limit. It is recommended that you canonicalize stage before passing it to this method, since the Windows canonical form lifts the path length limit to around 32,000 characters.

Example

extern crate rust_release_artefact as rra;

use std::error;
use std::fs;
use std::io;
use std::path;

fn extract_tar_gz_if_needed(
    source: &path::Path,
    stage: &path::Path,
) -> Result<rra::ExtractedArtefact, rra::Error> {

    // Before we go to all the effort of extracting this artefact,
    // perhaps it's already been extracted?
    match rra::ExtractedArtefact::new(stage) {

        // Yep, looks good, let's use it.
        Ok(extracted_artefact) => return Ok(extracted_artefact),

        // The stage is empty, let's continue extracting.
        Err(rra::Error::NoArtefacts(_)) => {}

        // The stage already contains a broken artefact,
        // and extracting another one won't help matters.
        Err(e) => return Err(e)
    }

    // Extract the given artefact.
    let handle = fs::File::open(source)?;
    let extracted_artefact = rra::ExtractedArtefact::from_tar_gz(
        io::BufReader::new(handle),
        stage,
    )?;

    // Everything's fine!
    Ok(extracted_artefact)
}

pub fn from_tar_gz<R: BufRead, P: AsRef<Path>>(
    source: R,
    stage: P
) -> Result<ExtractedArtefact, Error>

Extract an artefact in .tar.gz format and read its metadata.

The artefact source is extracted to the directory stage, and its content is read to produce an ExtractedArtefact. Nothing will be written outside stage, even if a malformed artefact attempts to do so.

stage must already exist and be writable; if it is not empty then the extracted artefact may be corrupted by the existing contents. You may want to create a fresh, temporary stage directory every time you want to examine an artefact, but since extraction is expensive you could also create a permanent directory with a predictable name. If the directory exists, pass it to the new() method, otherwise create it and pass it to this function.

If your artefact is in .tar.xz format, see from_tar_xz().

Errors

This function may return any of the variants of the Error enum.

If an error is returned, the staging area may be left in an invalid state. You may re-attempt extracting the same artefact to the staging area, but don't extract another artefact to it, or try to use it with the new() method.

Portability

Rust release artefacts may include a deeply-nested directory structure, which can exceed Windows' traditional 260 character limit. It is recommended that you canonicalize stage before passing it to this method, since the Windows canonical form lifts the path length limit to around 32,000 characters.

Example

extern crate rust_release_artefact as rra;

use std::fs;
use std::io;
use std::path;

let handle = fs::File::open("path/to/artefact.tar.gz")?;

// Make sure the staging area exists.
let staging_area = path::Path::new("path/to/staging/area");
fs::create_dir_all(&staging_area)?;

// Canonicalize the staging area path, so Windows can handle long path
// names.
let staging_area = staging_area.canonicalize()?;

let extracted_artefact = rra::ExtractedArtefact::from_tar_gz(
    io::BufReader::new(handle),
    staging_area,
)?;

pub fn from_tar_xz<R: BufRead, P: AsRef<Path>>(
    source: R,
    stage: P
) -> Result<ExtractedArtefact, Error>

Extract an artefact in .tar.xz format and read its metadata.

The artefact source is extracted to the directory stage, and its content is read to produce an ExtractedArtefact. Nothing will be written outside stage, even if a malformed artefact attempts to do so.

stage must already exist and be writable; if it is not empty then the extracted artefact may be corrupted by the existing contents. You may want to create a fresh, temporary stage directory every time you want to examine an artefact, but since extraction is expensive you could also create a permanent directory with a predictable name. If the directory exists, pass it to the new() method, otherwise create it and pass it to this function.

If your artefact is in .tar.gz format, see from_tar_gz().

Errors

This function may return any of the variants of the Error enum.

If an error is returned, the staging area may be left in an invalid state. You may re-attempt extracting the same artefact to the staging area, but don't extract another artefact to it, or try to use it with the new() method.

Portability

Rust release artefacts may include a deeply-nested directory structure, which can exceed Windows' traditional 260 character limit. It is recommended that you canonicalize stage before passing it to this method, since the Windows canonical form lifts the path length limit to around 32,000 characters.

Example

extern crate rust_release_artefact as rra;

use std::fs;
use std::io;
use std::path;

let handle = fs::File::open("path/to/artefact.tar.xz")?;

// Make sure the staging area exists.
let staging_area = path::Path::new("path/to/staging/area");
fs::create_dir_all(&staging_area)?;

// Canonicalize the staging area path, so Windows can handle long path
// names.
let staging_area = staging_area.canonicalize()?;

let extracted_artefact = rra::ExtractedArtefact::from_tar_xz(
    io::BufReader::new(handle),
    staging_area,
)?;

Trait Implementations

impl Clone for ExtractedArtefact

fn clone(&self) -> ExtractedArtefact

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ExtractedArtefact

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Hash for ExtractedArtefact

fn hash<__H: Hasher>(&self, __arg_0: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl PartialEq for ExtractedArtefact

fn eq(&self, __arg_0: &ExtractedArtefact) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, __arg_0: &ExtractedArtefact) -> bool

This method tests for !=.

impl Eq for ExtractedArtefact

impl PartialOrd for ExtractedArtefact

fn partial_cmp(&self, __arg_0: &ExtractedArtefact) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, __arg_0: &ExtractedArtefact) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, __arg_0: &ExtractedArtefact) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, __arg_0: &ExtractedArtefact) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, __arg_0: &ExtractedArtefact) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Ord for ExtractedArtefact

fn cmp(&self, __arg_0: &ExtractedArtefact) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.