Crate rust_releases[−][src]

Expand description

This crate aims to provide an index of Rust releases, and make it available to Rust programs.

Introduction

The Rust programming language uses deterministic versioning for toolchain releases. Stable versions use SemVer, while nightly, beta and historical builds can be accessed by using dated builds (YY-MM-DD).

Unfortunately, a complete index of releases is not available any more. There are however a few places where we can find partial release indices, from which we can build our own index.

This process consists of two parts: 1) obtaining the data sources, and 2) building the index from these data sources. For the first part rust-releases provides the FetchResources trait, and for the second part rust-releases provides the Source trait. Both traits find their origin in the rust-releases-core crate, and re-exported here.

Using `rust-releases`

To use this library, you can either add rust-releases-core as a dependency, combined with any implemented source library, or you can add rust-releases as a dependency, and enable the implemented source libraries of your choice as features.

By default, all four sources are enabled when depending on rust-releases. You can disable these by setting default-features = false for rust-releases in the Cargo.toml manifest, or by calling cargo with cargo --no-default-features. You can then cherry pick sources by adding the features key to the rust-releases dependency and enabling the features you want, or by calling cargo with cargo --features "rust-releases-rust-changelog,rust-releases-rust-dist" or any other combination of features and sources.

To use rust-releases, you must add at least one source implementation.

Example: using rust-releases-core + implemented source as dependency

To use rust-releases-core as a dependency, combined with any implemented source library; add the following to your Cargo.toml:

[dependencies]
rust-releases-core = "*"
rust-releases-$RUST_RELEASES_SOURCE

For example:

[dependencies]
rust-releases-core = "0.15.0"
rust-releases-rust-dist = "0.15.0"

Example using rust-releases + implemented source(s) as feature

To use rust-releases as a dependency, and enable the implemented source libraries of your choice as features, add the following to your Cargo.toml:

[dependencies.rust-releases]
version = "*"
default-features = false
features = ["rust-release-$RUST_RELEASES_SOURCE"]

For example:

[dependencies.rust-releases]
version = "0.15.0"
default-features = false
features = ["rust-release-rust-dist"]

Implemented sources

rust-releases provides four Source implementations. Three out of four also provide a FetchResources implementation. Each implementation requires adding the implementation crate as an additional dependency or feature (see using rust-releases.

The implementations are:

ChannelManifests: Build an index from Rust release manifests.
- Select this implementation by adding rust-releases-channel-manifests as a dependency
RustChangelog: Build an index from the RELEASES.md found in the root of the Rust source code repository.
- Select this implementation by adding rust-releases-rust-changelog as a dependency
RustDist: Build an index from the AWS S3 Rust distribution bucket; input data can be obtained using the FetchResources trait.
- Select this implementation by adding rust-releases-rust-dist as a dependency
RustDistWithCLI: Build an index from the AWS S3 Rust distribution bucket; obtain the input data yourself using the aws cli.
- Select this implementation by adding rust-releases-rust-dist-with-cli as a dependency

Choosing an implementation

When in doubt, use the RustChangelog source for stable releases, and RustDist for anything else. ChannelManifests should usually not be used, as it’s out of date (last checked April 2021; the last available input manifest is dated 2020-02-23). RustDistWithCLI requires manual input but pulls from the same data source as RustDist. The RustDist source is however more complete than the RustDistWithCLI source (as of April 2021).

In the below example, we’ll use one of the above sources (RustChangelog) to show you how you can use this library.

Example

use rust_releases_core::{FetchResources, Source, Channel, ReleaseIndex};
use rust_releases_rust_changelog::RustChangelog;

// We choose the RustChangelog source for this example; alternatives are RustDistWithCLI and ChannelManifests
let source = RustChangelog::fetch_channel(Channel::Stable).unwrap();

// Build a release index using our source of choice
let index = ReleaseIndex::from_source(source).unwrap();

// Do something with the release information
index.releases()
    .iter()
    .for_each(|release| {
        println!("release {:?}", release)
    });

Table of implemented features

Type of data source	Crate	Trait	Implemented	Channels¹	Speed^{2, 3}	On disk cache size⁴	Notes
ChannelManifests	`rust-releases-channel-manifests`	Source	✅	Stable, ~~Beta & Nightly~~^{Won't be implemented}	Medium	-	Deprecated: Input data has not been updated since 2020-02-23 ^(#9). Use `RustDist` instead.
ChannelManifests	`rust-releases-channel-manifests`	FetchResources	✅	Stable, ~~Beta & Nightly~~^{Won't be implemented}	Extremely slow (~1 hour)	~418 MB
RustChangelog	`rust-releases-rust-changelog`	Source	✅	Stable	Fast	-
RustChangelog	`rust-releases-rust-changelog`	FetchResources	✅	Stable	Instant (<1 second)	~491 KB
RustDist	`rust-releases-rust-dist`	Source	✅	Stable, ~~Beta & Nightly~~^{To be implemented}	Fast	-
RustDist	`rust-releases-rust-dist`	FetchResources	✅	Stable, ~~Beta & Nightly~~^{To be implemented}	Medium fast (~20 seconds)	~1 MB
RustDistWithCLI	`rust-releases-rust-dist-with-cli`	Source	✅	Stable	Fast	-
RustDistWithCLI	`rust-releases-rust-dist-with-cli`	FetchResources	❌	Stable	Slow (~1 minute)	~8 MB

¹: Currently most of the rust-releases public API supports only stable. Support for the beta and nightly channel is work-in-progress, and the table currently lists whether there is theoretical support for these channels.
²: Speed for the Source trait primarily consist of parsing speed
³: Speed for the FetchResources trait is primarily limited by your own download speed, and the rate limiting of the server from which the resources are fetched
⁴: Approximate as of 2021-03-03

linear

Provides an iterator over the latest patch versions for stable releases.

Structs

ChannelManifestsDeprecated

A Source which parses Rust release data from channel manifests, which used to be published for each release. Since 2020-02-23, however, no more channel manifests have been published.

Release

A Rust release with an associated version.

ReleaseIndex

A release index is a data structure holding known Rust releases.

RustChangelog

A Source which obtains release data from the official Rust changelog.

RustDist

A Source which obtains its input data from the Rust distribution bucket on AWS S3.

RustDistWithCLI

A Source which parses Rust release data from the AWS S3 index.