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 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. |