Crate rust_release_artefact [−] [src]
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 artifact'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 it's 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. 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; let handle = fs::File::open("path/to/artefact.tar.gz")?; let extracted_artefact = rra::ExtractedArtefact::from_tar_gz( io::BufReader::new(handle), "path/to/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?")?; component.install_to("path/to/install/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. |