76 lines
3.7 KiB
TOML
76 lines
3.7 KiB
TOML
# 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.
|