Crate version_check

Expand description

This tiny crate checks that the running or installed rustc meets some version requirements. The version is queried by calling the Rust compiler with --version. The path to the compiler is determined first via the RUSTC environment variable. If it is not set, then rustc is used. If that fails, no determination is made, and calls return None.

§Examples

Note: Please see feature detection for a note on enabling unstable features based on detection via this crate.

Set a cfg flag in build.rs if the running compiler was determined to be at least version 1.13.0:
```
extern crate version_check as rustc;

if rustc::is_min_version("1.13.0").unwrap_or(false) {
    println!("cargo:rustc-cfg=question_mark_operator");
}
```
See is_max_version or is_exact_version to check if the compiler is at most or exactly a certain version.

Check that the running compiler was released on or after 2018-12-18:

extern crate version_check as rustc;

match rustc::is_min_date("2018-12-18") {
    Some(true) => "Yep! It's recent!",
    Some(false) => "No, it's older.",
    None => "Couldn't determine the rustc version."
};

See is_max_date or is_exact_date to check if the compiler was released prior to or exactly on a certain date.

Check that the running compiler supports feature flags:

extern crate version_check as rustc;

match rustc::is_feature_flaggable() {
    Some(true) => "Yes! It's a dev or nightly release!",
    Some(false) => "No, it's stable or beta.",
    None => "Couldn't determine the rustc version."
};

Please see the note on feature detection.

Check that the running compiler supports a specific feature:

extern crate version_check as rustc;

if let Some(true) = rustc::supports_feature("doc_cfg") {
   println!("cargo:rustc-cfg=has_doc_cfg");
}

Please see the note on feature detection.

Check that the running compiler is on the stable channel:

extern crate version_check as rustc;

match rustc::Channel::read() {
    Some(c) if c.is_stable() => format!("Yes! It's stable."),
    Some(c) => format!("No, the channel {} is not stable.", c),
    None => format!("Couldn't determine the rustc version.")
};

To interact with the version, release date, and release channel as structs, use Version, Date, and Channel, respectively. The triple() function returns all three values efficiently.

§Feature Detection

While this crate can be used to determine if the current compiler supports an unstable feature, no crate can determine whether that feature will work in a way that you expect ad infinitum. If the feature changes in an incompatible way, then your crate, as well as all of its transitive dependents, will fail to build. As a result, great care should be taken when enabling nightly features even when they’re supported by the compiler.

One common mitigation used in practice is to make using unstable features transitively opt-in via a crate feature or cfg so that broken builds only affect those that explicitly asked for the feature. Another complementary approach is to probe rustc at build-time by asking it to compile a small but exemplary program that determines whether the feature works as expected, enabling the feature only if the probe succeeds. Finally, eschewing these recommendations, you should track the nightly channel closely to minimize the total impact of a nightly breakages.

§Alternatives

This crate is dead simple with no dependencies. If you need something more and don’t care about panicking if the version cannot be obtained, or if you don’t mind adding dependencies, see rustc_version.

Structs§

Channel: Release channel: “dev”, “nightly”, “beta”, or “stable”.
Date: Release date including year, month, and day.
Version: Version number: major.minor.patch, ignoring release channel.

Functions§

is_exact_date: Checks that the running or installed rustc was released exactly on some date.
is_exact_version: Checks that the running or installed rustc is exactly some version.
is_feature_flaggable: Checks whether the running or installed rustc supports feature flags.
is_max_date: Checks that the running or installed rustc was released on or before some date.
is_max_version: Checks that the running or installed rustc is at most some maximum version.
is_min_date: Checks that the running or installed rustc was released on or after some date.
is_min_version: Checks that the running or installed rustc is at least some minimum version.
supports_feature: Checks whether the running or installed rustc supports feature.
triple: Reads the triple of Version, Channel, and Date of the installed or running rustc.