tame/tamer/rust-toolchain.toml

76 lines
3.7 KiB
TOML
Raw Blame History

This file contains invisible Unicode characters!

This file contains invisible Unicode characters that may be processed differently from what appears below. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to reveal hidden characters.

# 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.