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
- Select this implementation by adding
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
- Select this implementation by adding
RustDist
: Build an index from the AWS S3 Rust distribution bucket; input data can be obtained using theFetchResources
trait.- Select this implementation by adding
rust-releases-rust-dist
as a dependency
- Select this implementation by adding
RustDistWithCLI
: Build an index from the AWS S3 Rust distribution bucket; obtain the input data yourself using theaws
cli.- Select this implementation by adding
rust-releases-rust-dist-with-cli
as a dependency
- Select this implementation by adding
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 | Channels1 | Speed2, 3 | On disk cache size4 | Notes |
---|---|---|---|---|---|---|---|
ChannelManifests | rust-releases-channel-manifests |
Source | ✅ | Stable, |
Medium | - | Deprecated: Input data has not been updated since 2020-02-23 (#9). Use RustDist instead. |
FetchResources | ✅ | Extremely slow (~1 hour) | ~418 MB | ||||
RustChangelog | rust-releases-rust-changelog |
Source | ✅ | Stable | Fast | - | |
FetchResources | ✅ | Instant (<1 second) | ~491 KB | ||||
RustDist | rust-releases-rust-dist |
Source | ✅ | Stable, |
Fast | - | |
FetchResources | ✅ | Medium fast (~20 seconds) | ~1 MB | ||||
RustDistWithCLI | rust-releases-rust-dist-with-cli |
Source | ✅ | Stable | Fast | - | |
FetchResources | ❌ | Slow (~1 minute) | ~8 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
Provides a binary search operation which is intended to be used to search for the lowest required version.
Provides an iterator over the latest patch versions for stable releases.
Structs
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.
A Rust release with an associated version.
A release index is a data structure holding known Rust releases.
A Source
which obtains release data from the official Rust changelog.
A Source
which obtains its input data from the Rust distribution bucket on AWS S3.
A Source
which parses Rust release data from the AWS S3 index.
Enums
Enumerates the Rust release channels
Top level failure cases for rust-releases-channel-manifests source crate
Top level failure cases for rust-releases-core
Top level failure cases for rust-releases-rust-changelog source crate
Top level failure cases for rust-releases-rust-dist source crate
Top level failure cases for rust-releases-rust-dist-with-cli source crate
Traits
With FetchResources
, the set of inputs required to build a release index can be fetched.
A Source
is a set of inputs from which a release index can be built.
Type Definitions
A result type which binds the ChannelManifestsError
to the error type.
A result type which binds the CoreError
to the error type.
A result type which binds the RustChangelogError
to the error type.
A result type which binds the RustDistError
to the error type.
A result type which binds the RustDistWithCLIError
to the error type.