# See <https://rust-lang.github.io/rustup/overrides.html?highlight=rust-toolchain#the-toolchain-file>
#
# This file is used to pin the version of Rust used to build TAMER.  This is
# not at all an ideal situation, but is necessary because TAMER uses nightly
# features, and those features will occaisonally make
# backwards-incompatabile changes.
#
# The default behavior caused by this file is not ideal:  If the user uses
# rustup, it'll cause the toolchain to be downloaded during build,
# _ignoring_ any `--offline` flag provided to Cargo.  Projects ought to be
# able to build without network access; the `bootstrap` script is intended
# to install necessary dependencies on a system prior to building.
#
# By explicitly specifying the toolchain via `cargo +toolchain`, we bypass
# the system utilizing this file.  It becomes clear that TAMER is being
# compiled with a particular toolchain version---the invoked command (by
# `make`) explicitly says so.  This also avoids automatically downloading
# the toolchain if it's missing, relying instead on any prior bootstrapping
# or system-installed toolchain.
#
# Why have `rust-toolchain.toml` at all, then?  Because then `cargo` will
# work when invoked independently, if someone chooses not to use `make` for
# any reason.  It is still recommended that `make` be utilized so that all
# the other build configuration takes effect.
#
# `configure.ac` will extract the channel from this file and utilize it to
# configure the build to explicitly pass the channel via each cargo
# invocation via the `Makefile`.  Changing this file will will cause
# reconfiguration automatically.
#
# Alternatively, `TAMER_RUST_TOOLCHAIN` may be used to explicitly specify
# the channel for the toolchain.  If you do this, then modifying
# `rust-toolchain.toml` will _not_ trigger a reconfiguration automatically.
#
# If you are building an earlier commit that does not have this file, then
# you will need to modify `configure.ac` / `Makefile.am` to do your bidding.

[toolchain]
channel = "nightly-2023-04-15" #¹

# The components should be checked in `configure.ac`
#   - Note that `cargo-fmt` is `rustfmt`.
components = ["rustfmt", "clippy"]

# A note on the above version: it's not likely to be the case that _this
# specific version_ is necessary to build TAMER.  Instead, this is an upper
# bound, whereas the Rust version in `configure.ac` is a lower bound.  Some,
# or all, of the versions within that bound are likely to work.  If you know
# another version that works (e.g. you are packaging TAMER and want to use
# another version of Rust already available elsewhere), you may use the
# `TAMER_RUST_TOOLCHAIN` `configure` parameter.


# ¹ TAMER uses the incomplete feature `adt_const_params`.  "Incomplete"
# features require a special flag to enable---`incomplete_features`---and
# are described as "incomplete and may not be safe to use and/or cause
# compiler crashes".
#
# The `ConstParamTy` trait was introduced by
# <https://github.com/rust-lang/rust/pull/111670> and merged in early
# June 2023.  After this change, const params types must implement this
# trait.
#
# Unfortunately, at the time of writing (2023-06), while the trait is
# implemented on a number of core primitives, it is _not_ implemented on the
# `NonZero*` types.  There is an inquiry into this limitation on Zulip, and
# it is expected to be resolved in the future:
#   <https://rust-lang.zulipchat.com/#narrow/stream/182449-t-compiler.2Fhelp/topic/ConstParamTy.20for.20NonZero*.20types>
#
# We will sit on this and watch how it evolves over the following
# weeks/months to assess how to best proceed.
#
# Aside from this, there seems to be a rustdoc bug at some point between
# April and June that causes documentation failures.  This needs further
# investigation, and possibly a bug report.
