Crate rust_release_channel

A data structure for Rust release channel metadata

Introduction

New versions of the Rust toolchain are released on a regular six-week cycle. Each version is described in a release-channel metadata file in a known location, allowing automated tools to detect new releases and find the tools and components for each supported platform.

The data structures in this library represent the information present in each metadata file, organised to help you pull out the specific information you need.

This library is designed to handle version 2 of the manifest file format.

The most important class is Channel, so you’ll want to start there.

First Example

extern crate rust_release_channel;
use std::error::Error;

fn dump_manifest_info(input: &str) -> Result<(), Box<Error>> {
    // Parse the manifest into a data structure.
    let channel: rust_release_channel::Channel = input.parse()?;

    // Check the manifest is sensible before we use it.
    let errors = channel.validate();
    if errors.is_empty() {
        // Dump a summary of the manifest data
        println!(
            "Channel manifest created on {}",
            channel.date,
        );
        println!("Included packages:");
        for (name, pkg) in channel.pkg.iter() {
            println!("  - {} version {}", name, pkg.version);
        }
    } else {
        println!("Channel has problems:");
        for each in errors {
            println!("  - {}", each);
        }
    }

    Ok(())
}

Capabilities

Reading manifests

If you can read the content of an existing manifest file, you can turn it into a queryable, explorable data structure with the .parse() method (courtesy of the standard FromStr trait).

use rust_release_channel::Channel;

let channel: Channel = my_str.parse()?;

After reading a manifest, you should call .validate() to see if the data makes sense before trusting it.

Querying manifests

All the content of the manifest is available to inspect, as native-feeling Rust data structures. For example, where the native manifest file-format models different available file-formats as differently-named keys with the same meaning (url vs. xz_url, hash vs. xz_hash), rust_release_channel gives you a mapping from ArchiveFormat to ArchiveSource.

use rust_release_channel::{ArtefactQuery, ArchiveFormat};

let rust_for_aarch64_url = channel.lookup_artefact(
        ArtefactQuery::new("rust", "aarch64-unknown-linux-gnu"),
    )
    .and_then(|artefact| {
         artefact.standalone.get(&ArchiveFormat::TarGzip)
    })
    .map(|archive| { &archive.url });

Creating fresh manifests

You can also create manifest data completely from scratch, in case you need to create test-data for another system.

use rust_release_channel::{
    Channel,
    Package,
    Artefact,
    ArchiveFormat,
    ArchiveSource,
};

let source = ArchiveSource::new(
    "https://example.com/rust/mypackage-linux-x86.tar.gz".parse()?,
    "aa0a89d80329fec6f9e84b79c1674c5427034408630c35da1be442c7da6d2364"
        .into(),
);

let mut artefact = Artefact::new();
artefact.standalone.insert(ArchiveFormat::TarGzip, source);

let mut mypackage = Package::new("1.2.3 (abc1234 2018-02-26)".into());
mypackage.target.insert("x86_64-unknown-linux-gnu".into(), artefact);

let mut channel = Channel::new();
channel.pkg.insert("mypackage".into(), mypackage);

Writing manifests

You can turn manifest data back into a string with the .to_string() method. If you serialize a Channel and deserialize it again, the result should be identical to the original.

let manifest_string = channel.to_string()?;

Before writing a manifest, you should call .validate() to check you haven’t left the metadata in an inconsistent state.

Structs

ArchiveSource

Describes where to obtain a particular archive.

Artefact

One or more packages built for a single target.

ArtefactQuery

Names an Artefact that might exist in a channel.

ArtefactToken

Stores the identity of an Artefact in a channel.

Channel

The metadata for a Rust release channel.

Package

A single package installable from this release channel.

Enums

ArchiveFormat

Represents the formats used by archives from this channel.

ValidationError

Possible ways in which channel metadata could be inconsistent.