Expand description
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§
- Archive
Source - Describes where to obtain a particular archive.
- Artefact
- One or more packages built for a single target.
- Artefact
Query - Names an
Artefact
that might exist in a channel. - Artefact
Token - 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§
- Archive
Format - Represents the formats used by archives from this channel.
- Validation
Error - Possible ways in which channel metadata could be inconsistent.