Crate rust_releases

source ·
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:

# replace `*` with latest version, and
# replace `$RUST_RELEASES_SOURCE` with one of the implemented source crates
[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:

# replace `*` with latest version, and replace `$RUST_RELEASES_SOURCE` with one of the available source implementations
[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:

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

§Choosing an implementation

When in doubt, use the RustChangelog source for stable releases, and RustDist for anything else.

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 Channels1 Speed2, 3 On disk cache size4 Notes
RustChangelog rust-releases-rust-changelog Source ✅ Stable Fast -
FetchResources ✅ Instant (<1 second) ~491 KB
RustDist rust-releases-rust-dist Source ✅ Stable, Beta & NightlyTo be implemented Fast -
FetchResources ✅ Medium fast (~20 seconds) ~1 MB

1: 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.
2: Speed for the Source trait primarily consist of parsing speed
3: 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
4: Approximate as of 2021-03-03

§Issues

Feel free to open an issue at our repository for questions, feature requests, bug fixes, or other points of feedback 🤗.

Re-exports§

  • pub use rust_releases_core::semver;

Modules§

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

Structs§

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

Enums§

  • Channel
    Enumerates the Rust release channels
  • CoreError
    Top level failure cases for rust-releases-core
  • RustChangelogError
    Top level failure cases for rust-releases-rust-changelog source crate

Traits§

  • FetchResources
    With FetchResources, the set of inputs required to build a release index can be fetched.
  • Source
    A Source is a set of inputs from which a release index can be built.

Type Aliases§

  • CoreResult
    A result type which binds the CoreError to the error type.
  • RustChangelogResult
    A result type which binds the RustChangelogError to the error type.