There is no special consideration for nightly crates nor is there a standardized way to indicate that it relies on unstable features as far as I know.

• rust-toolchain.toml is not considered by downstream builds
• there is rust-version that you can specify in your Cargo.toml, but specifying a nightly version either doesn’t work or is ignored

The best way to publish a nightly crate is to make it clear in your readme that it relies on the nightly compiler. And even then, a user attempting to use it on a stable release will see “#![feature] may not be used on the stable release channel” errors – which is hopefully clear enough.

One way is to use Feature Gates.
(This only makes sense if there is some basic functionality that works in stable).

[features]
# Defines a feature named `nightly` that does not
# enable any other features.
nightly = []

Then we can annotate code with #[cfg(feature = "nightly")] like this:

#[cfg(feature = "nightly")]
impl std::iter::Step for TileIndex {
...
}

This code will only be included if the feature flag is set by the consumer. That is, they need to either use cargo build --features nightly or specify the dependency in their own Cargo.toml with the feature flag:

derive_more = { version = "1", features = ["nightly"] }

This makes it possible to ship the crate with some functionality that works in stable rust, and optionally make the rest of the functions available.

The #[cfg(feature = "nightly")] annotation can also be used before functions, or before code blocks within a function. However, I ran into one such case where the skipped code would cause syntax errors (because I used yield there, which is not yet stable). In that case, the crate cfg_if helps:

cfg_if::cfg_if! {if #[cfg(feature = "nightly")] {
impl IntoIterator for MovementRange {
...
}
}

In either case, this only skips including the code, but it would still not work with cargo +stable build, because the #![feature(...)] annotations may only be used in nightly. To skip them too, you can use cfg_attr which does the same thing as cfg, but for attributes:

// We have code that uses the nightly toolchain. It is gated behind the "nightly" crate feature flag.
// This means the crate can still be used with stable rust - it will just not have all functions.
#![cfg_attr(feature = "nightly", feature(step_trait))]
#![cfg_attr(feature = "nightly", feature(coroutines))]
#![cfg_attr(feature = "nightly", feature(iter_from_coroutine))]
#![cfg_attr(feature = "nightly", feature(impl_trait_in_assoc_type))]

To test where such an attribute was used, you can first set it to conditional compilation like I just showed, and then build with cargo +nightly build, which does not automatically contain the feature flag "nightly" and will tell you what code would need the feature, so you can go and exclude it with #[cfg( feature = "nightly")].

I don’t know whether this is a good way. But after these changes:

• My crate builds basic functionality with cargo +stable build
• All functions still work with cargo +nightly build

• Note: Rustdoc has experimental support for annotating the documentation to indicate which features are required to use certain APIs.

  • However, this itself is an unstable feature.. You can again feature-gate that, but in the end that means that only the cargo +nightly doc will show this information.