Crate rust_release_artefact

Safely extract installable files from Rust release artefacts.

Introduction

Each new release of the Rust toolchain includes a number of components—some required, some optional—that can be combined together. These components are made available as artefacts in a standard format that includes the files to be installed, as well as metadata describing them. Installing a component is therefore more complex than just extracting an archive, since not all files should be placed in the destination.

This library interprets a Rust artefact's metadata, and provides a list of the components it contains, as well as the specific list of installable files in each component.

Once you've downloaded an artefact, use ExtractedArtefact::from_tar_gz() or ExtractedArtefact::from_tar_xz() to extract it and retrieve the metadata (the place you got the artefact from should tell you which format it's in). If you have previously extracted an artefact, you can re-read the metadata directly using ExtractedArtefact::new().

First Example

extern crate rust_release_artefact as rra;

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

fn install_from_tar_gz(
    artefact_path: &path::Path,
    stage: &path::Path,
    component_name: &str,
    dest_root: &path::Path,
) -> Result<(), Box<error::Error>> {
    // Open the file containing the artefact.
    let handle = fs::File::open(artefact_path)?;

    // Extract it to the given staging path and read the metadata.
    // We're assuming the staging path is already canonicalized, and
    // the artefact is in .tar.gz format.
    let extracted_artefact = rra::ExtractedArtefact::from_tar_gz(
        io::BufReader::new(handle),
        stage,
    )?;

    // Get the requested component from the artefact.
    let component = extracted_artefact.components
        .get(component_name)
        .ok_or("Could not find component")?;

    println!(
        "Installing component {} version {} to {:?}",
        component_name,
        extracted_artefact.version,
        dest_root,
    );

    // Install the component into the destination.
    // We're also assuming dest_root is already canonicalized.
    component.install_to(dest_root)?;

    // All done!
    Ok(())
}

Capabilities

Extract downloaded artefacts

Once you have downloaded a release artefact, you can extract it into a staging area with the ExtractedArtefact::from_tar_gz() or ExtractedArtefact::from_tar_xz() functions (depending on the format).

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,
)?;

Read artefact metadata

An ExtractedArtefact struct represents the artefact's metadata, including the components in this artefact and the complete list of installable files in each component.

println!("Version: {:?}", extracted_artefact.version);
println!("Git commit hash: {:?}", extracted_artefact.git_commit_hash);

for (name, component) in &extracted_artefact.components {
    println!("Component: {:?} in {:?}", name, component.root);
    for path in &component.files {
        println!("  - {:?}", path);
    }
}

Install components to a given destination

The Component struct represents an installable component of the artefact, whose files are in the artefact's staging area, ready to be installed to a target location. The handy Component::install_to() method does exactly that.

let component = extracted_artefact.components.get("my-component")
    .ok_or("no such component?")?;

// Make sure the destination exists.
let destination = std::path::Path::new("path/to/install/destination");
std::fs::create_dir_all(&destination)?;

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

component.install_to(destination)?;

Structs

Component	An installable component of an artefact.
ExtractedArtefact	The metadata and content of a previously-extracted artefact.

Enums

Error

All the possible errors this crate can produce.