mirror of https://github.com/rust-lang/rust.git
More config.toml.example cleanups
- Link to more documentation - Move `changelog-seen` into the "Global Settings" section - Update incorrect comments on `llvm.link-shared` and `rust.debug-assertions` - Use the correct default in the commented-out example more often - Clarify that `docs` and `compiler-docs` only control the default, they're not a hard-off switch. - Document `-vvv` and `local-rebuild` - Minor improvements to doc-comments in config.toml.example This also sets `download-rustc = false`; that was already the default, but it will be helpful in case the default changes (https://jyn.dev/2023/01/12/Bootstrapping-Rust-in-2023.html).
This commit is contained in:
Joshua Nelson
Jynn Nelson
parent
7a0600714a
commit
20ca24e3c5
|
|
@ -1,7 +1,7 @@
|
|||
# Sample TOML configuration file for building Rust.
|
||||
#
|
||||
# To configure rustbuild, copy this file to the directory from which you will be
|
||||
# running the build, and name it config.toml.
|
||||
# To configure rustbuild, run `./configure` or `./x.py setup`.
|
||||
# See https://rustc-dev-guide.rust-lang.org/building/how-to-build-and-run.html#create-a-configtoml for more information.
|
||||
#
|
||||
# All options are commented out by default in this file, and they're commented
|
||||
# out with their default values. The build system by default looks for
|
||||
|
|
@ -9,12 +9,6 @@
|
|||
# a custom configuration file can also be specified with `--config` to the build
|
||||
# system.
|
||||
|
||||
# Keeps track of the last version of `x.py` used.
|
||||
# If it does not match the version that is currently running,
|
||||
# `x.py` will prompt you to update it and read the changelog.
|
||||
# See `src/bootstrap/CHANGELOG.md` for more information.
|
||||
changelog-seen = 2
|
||||
|
||||
# =============================================================================
|
||||
# Global Settings
|
||||
# =============================================================================
|
||||
|
|
@ -25,6 +19,12 @@ changelog-seen = 2
|
|||
# Note that this has no default value (x.py uses the defaults in `config.toml.example`).
|
||||
#profile = <none>
|
||||
|
||||
# Keeps track of the last version of `x.py` used.
|
||||
# If `changelog-seen` does not match the version that is currently running,
|
||||
# `x.py` will prompt you to update it and to read the changelog.
|
||||
# See `src/bootstrap/CHANGELOG.md` for more information.
|
||||
changelog-seen = 2
|
||||
|
||||
# =============================================================================
|
||||
# Tweaking how LLVM is compiled
|
||||
# =============================================================================
|
||||
|
|
@ -33,7 +33,7 @@ changelog-seen = 2
|
|||
# Whether to use Rust CI built LLVM instead of locally building it.
|
||||
#
|
||||
# Unless you're developing for a target where Rust CI doesn't build a compiler
|
||||
# toolchain or changing LLVM locally, you probably want to set this to true.
|
||||
# toolchain or changing LLVM locally, you probably want to leave this enabled.
|
||||
#
|
||||
# All tier 1 targets are currently supported; set this to `"if-available"` if
|
||||
# you are not sure whether you're on a tier 1 target.
|
||||
|
|
@ -42,9 +42,7 @@ changelog-seen = 2
|
|||
#
|
||||
# Note that many of the LLVM options are not currently supported for
|
||||
# downloading. Currently only the "assertions" option can be toggled.
|
||||
#
|
||||
# Defaults to "if-available" when `channel = "dev"` and "false" otherwise.
|
||||
#download-ci-llvm = "if-available"
|
||||
#download-ci-llvm = if rust.channel == "dev" { "if-available" } else { false }
|
||||
|
||||
# Indicates whether the LLVM build is a Release or Debug build
|
||||
#optimize = true
|
||||
|
|
@ -59,6 +57,8 @@ changelog-seen = 2
|
|||
#release-debuginfo = false
|
||||
|
||||
# Indicates whether the LLVM assertions are enabled or not
|
||||
# NOTE: When assertions are disabled, bugs in the integration between rustc and LLVM can lead to
|
||||
# unsoundness (segfaults, etc.) in the rustc process itself, not just in the generated code.
|
||||
#assertions = false
|
||||
|
||||
# Indicates whether the LLVM testsuite is enabled in the build or not. Does
|
||||
|
|
@ -70,10 +70,9 @@ changelog-seen = 2
|
|||
# Indicates whether the LLVM plugin is enabled or not
|
||||
#plugins = false
|
||||
|
||||
# Indicates whether ccache is used when building LLVM
|
||||
# Indicates whether ccache is used when building LLVM. Set to `true` to use the first `ccache` in
|
||||
# PATH, or set an absolute path to use a specific version.
|
||||
#ccache = false
|
||||
# or alternatively ...
|
||||
#ccache = "/path/to/ccache"
|
||||
|
||||
# When true, link libstdc++ statically into the rustc_llvm.
|
||||
# This is useful if you don't want to use the dynamic version of that
|
||||
|
|
@ -87,11 +86,8 @@ changelog-seen = 2
|
|||
# Note: this is NOT related to Rust compilation targets. However, as Rust is
|
||||
# dependent on LLVM for code generation, turning targets off here WILL lead to
|
||||
# the resulting rustc being unable to compile for the disabled architectures.
|
||||
# Also worth pointing out is that, in case support for new targets are added to
|
||||
# LLVM, enabling them here doesn't mean Rust is automatically gaining said
|
||||
# support. You'll need to write a target specification at least, and most
|
||||
# likely, teach rustc about the C ABI of the target. Get in touch with the
|
||||
# Rust team and file an issue if you need assistance in porting!
|
||||
#
|
||||
# To add support for new targets, see https://rustc-dev-guide.rust-lang.org/building/new-target.html.
|
||||
#targets = "AArch64;ARM;BPF;Hexagon;MSP430;Mips;NVPTX;PowerPC;RISCV;Sparc;SystemZ;WebAssembly;X86"
|
||||
|
||||
# LLVM experimental targets to build support for. These targets are specified in
|
||||
|
|
@ -104,19 +100,18 @@ changelog-seen = 2
|
|||
# This can be useful when building LLVM with debug info, which significantly
|
||||
# increases the size of binaries and consequently the memory required by
|
||||
# each linker process.
|
||||
# If absent or 0, linker invocations are treated like any other job and
|
||||
# If set to 0, linker invocations are treated like any other job and
|
||||
# controlled by rustbuild's -j parameter.
|
||||
#link-jobs = 0
|
||||
|
||||
# When invoking `llvm-config` this configures whether the `--shared` argument is
|
||||
# passed to prefer linking to shared libraries.
|
||||
# NOTE: `thin-lto = true` requires this to be `true` and will give an error otherwise.
|
||||
#link-shared = false
|
||||
# Whether to build LLVM as a dynamically linked library (as opposed to statically linked).
|
||||
# Under the hood, this passes `--shared` to llvm-config.
|
||||
# NOTE: To avoid performing LTO multiple times, we suggest setting this to `true` when `thin-lto` is enabled.
|
||||
#link-shared = llvm.thin-lto
|
||||
|
||||
# When building llvm, this configures what is being appended to the version.
|
||||
# The default is "-rust-$version-$channel", except for dev channel where rustc
|
||||
# version number is omitted. To use LLVM version as is, provide an empty string.
|
||||
#version-suffix = "-rust-dev"
|
||||
# To use LLVM version as is, provide an empty string.
|
||||
#version-suffix = if rust.channel == "dev" { "-rust-dev" } else { "-rust-$version-$channel" }
|
||||
|
||||
# On MSVC you can compile LLVM with clang-cl, but the test suite doesn't pass
|
||||
# with clang-cl, so this is special in that it only compiles LLVM with clang-cl.
|
||||
|
|
@ -178,47 +173,58 @@ changelog-seen = 2
|
|||
# The default stage to use for the `bench` subcommand
|
||||
#bench-stage = 2
|
||||
|
||||
# Build triple for the original snapshot compiler. This must be a compiler that
|
||||
# nightlies are already produced for. The current platform must be able to run
|
||||
# binaries of this build triple and the nightly will be used to bootstrap the
|
||||
# first compiler.
|
||||
# Build triple for the pre-compiled snapshot compiler. If `rustc` is set, this must match its host
|
||||
# triple (see `rustc --version --verbose`; cross-compiling the rust build system itself is NOT
|
||||
# supported). If `rustc` is unset, this must be a platform with pre-compiled host tools
|
||||
# (https://doc.rust-lang.org/nightly/rustc/platform-support.html). The current platform must be
|
||||
# able to run binaries of this build triple.
|
||||
#
|
||||
# Defaults to platform where `x.py` is run.
|
||||
# If `rustc` is present in path, this defaults to the host it was compiled for.
|
||||
# Otherwise, `x.py` will try to infer it from the output of `uname`.
|
||||
# If `uname` is not found in PATH, we assume this is `x86_64-pc-windows-msvc`.
|
||||
# This may be changed in the future.
|
||||
#build = "x86_64-unknown-linux-gnu" (as an example)
|
||||
|
||||
# Which triples to produce a compiler toolchain for. Each of these triples will
|
||||
# be bootstrapped from the build triple themselves.
|
||||
# Which triples to produce a compiler toolchain for. Each of these triples will be bootstrapped from
|
||||
# the build triple themselves. In other words, this is the list of triples for which to build a
|
||||
# compiler that can RUN on that triple.
|
||||
#
|
||||
# Defaults to just the build triple.
|
||||
#host = ["x86_64-unknown-linux-gnu"] (as an example)
|
||||
# Defaults to just the `build` triple.
|
||||
#host = [build.build] (list of triples)
|
||||
|
||||
# Which triples to build libraries (core/alloc/std/test/proc_macro) for. Each of
|
||||
# these triples will be bootstrapped from the build triple themselves.
|
||||
# Which triples to build libraries (core/alloc/std/test/proc_macro) for. Each of these triples will
|
||||
# be bootstrapped from the build triple themselves. In other words, this is the list of triples for
|
||||
# which to build a library that can CROSS-COMPILE to that triple.
|
||||
#
|
||||
# Defaults to `host`. If you set this explicitly, you likely want to add all
|
||||
# host triples to this list as well in order for those host toolchains to be
|
||||
# able to compile programs for their native target.
|
||||
#target = ["x86_64-unknown-linux-gnu"] (as an example)
|
||||
#target = build.host (list of triples)
|
||||
|
||||
# Use this directory to store build artifacts.
|
||||
# You can use "$ROOT" to indicate the root of the git repository.
|
||||
# Use this directory to store build artifacts. Paths are relative to the current directory, not to
|
||||
# the root of the repository.
|
||||
#build-dir = "build"
|
||||
|
||||
# Instead of downloading the src/stage0.json version of Cargo specified, use
|
||||
# this Cargo binary instead to build all Rust code
|
||||
# If you set this, you likely want to set `rustc` as well.
|
||||
#cargo = "/path/to/cargo"
|
||||
|
||||
# Instead of downloading the src/stage0.json version of the compiler
|
||||
# specified, use this rustc binary instead as the stage0 snapshot compiler.
|
||||
# If you set this, you likely want to set `cargo` as well.
|
||||
#rustc = "/path/to/rustc"
|
||||
|
||||
# Instead of download the src/stage0.json version of rustfmt specified,
|
||||
# Instead of downloading the src/stage0.json version of rustfmt specified,
|
||||
# use this rustfmt binary instead as the stage0 snapshot rustfmt.
|
||||
#rustfmt = "/path/to/rustfmt"
|
||||
|
||||
# Flag to specify whether any documentation is built. If false, rustdoc and
|
||||
# Whether to build documentation by default. If false, rustdoc and
|
||||
# friends will still be compiled but they will not be used to generate any
|
||||
# documentation.
|
||||
#
|
||||
# You can still build documentation when this is disabled by explicitly passing paths,
|
||||
# e.g. `x doc library`.
|
||||
#docs = true
|
||||
|
||||
# Flag to specify whether CSS, JavaScript, and HTML are minified when
|
||||
|
|
@ -229,8 +235,8 @@ changelog-seen = 2
|
|||
# Flag to specify whether private items should be included in the library docs.
|
||||
#library-docs-private-items = false
|
||||
|
||||
# Indicate whether the compiler should be documented in addition to the standard
|
||||
# library and facade crates.
|
||||
# Indicate whether to build compiler documentation by default.
|
||||
# You can still build documentation when this is disabled by explicitly passing a path: `x doc compiler`.
|
||||
#compiler-docs = false
|
||||
|
||||
# Indicate whether git submodules are managed and updated automatically.
|
||||
|
|
@ -247,14 +253,14 @@ changelog-seen = 2
|
|||
# Python interpreter to use for various tasks throughout the build, notably
|
||||
# rustdoc tests, the lldb python interpreter, and some dist bits and pieces.
|
||||
#
|
||||
# Defaults to the Python interpreter used to execute x.py
|
||||
# Defaults to the Python interpreter used to execute x.py.
|
||||
#python = "python"
|
||||
|
||||
# The path to the REUSE executable to use. Note that REUSE is not required in
|
||||
# most cases, as our tooling relies on a cached (and shrinked) copy of the
|
||||
# REUSE output present in the git repository and in our source tarballs.
|
||||
#
|
||||
# REUSE is only needed if your changes caused the overral licensing of the
|
||||
# REUSE is only needed if your changes caused the overall licensing of the
|
||||
# repository to change, and the cached copy has to be regenerated.
|
||||
#
|
||||
# Defaults to the "reuse" command in the system path.
|
||||
|
|
@ -264,14 +270,19 @@ changelog-seen = 2
|
|||
# set that all the Cargo.toml files create, instead of updating it.
|
||||
#locked-deps = false
|
||||
|
||||
# Indicate whether the vendored sources are used for Rust dependencies or not
|
||||
# Indicate whether the vendored sources are used for Rust dependencies or not.
|
||||
#
|
||||
# Vendoring requires additional setup. We recommend using the pre-generated source tarballs if you
|
||||
# want to use vendoring. See
|
||||
# https://forge.rust-lang.org/infra/other-installation-methods.html#source-code.
|
||||
#vendor = false
|
||||
|
||||
# Typically the build system will build the Rust compiler twice. The second
|
||||
# compiler, however, will simply use its own libraries to link against. If you
|
||||
# would rather to perform a full bootstrap, compiling the compiler three times,
|
||||
# then you can set this option to true. You shouldn't ever need to set this
|
||||
# option to true.
|
||||
# then you can set this option to true.
|
||||
#
|
||||
# This is only useful for verifying that rustc generates reproducible builds.
|
||||
#full-bootstrap = false
|
||||
|
||||
# Enable a build of the extended Rust tool set which is not only the compiler
|
||||
|
|
@ -300,7 +311,7 @@ changelog-seen = 2
|
|||
# "rust-demangler", # if profiler = true
|
||||
#]
|
||||
|
||||
# Verbosity level: 0 == not verbose, 1 == verbose, 2 == very verbose
|
||||
# Verbosity level: 0 == not verbose, 1 == verbose, 2 == very verbose, 3 == print environment variables on each rustc invocation
|
||||
#verbose = 0
|
||||
|
||||
# Build the sanitizer runtimes
|
||||
|
|
@ -320,11 +331,12 @@ changelog-seen = 2
|
|||
|
||||
# Arguments passed to the `./configure` script, used during distcheck. You
|
||||
# probably won't fill this in but rather it's filled in by the `./configure`
|
||||
# script.
|
||||
# script. Useful for debugging.
|
||||
#configure-args = []
|
||||
|
||||
# Indicates that a local rebuild is occurring instead of a full bootstrap,
|
||||
# essentially skipping stage0 as the local compiler is recompiling itself again.
|
||||
# Useful for modifying only the stage2 compiler without having to pass `--keep-stage 0` each time.
|
||||
#local-rebuild = false
|
||||
|
||||
# Print out how long each rustbuild step took (mostly intended for CI and
|
||||
|
|
@ -354,10 +366,10 @@ changelog-seen = 2
|
|||
# =============================================================================
|
||||
[install]
|
||||
|
||||
# Instead of installing to /usr/local, install to this path instead.
|
||||
# Where to install the generated toolchain. Must be an absolute path.
|
||||
#prefix = "/usr/local"
|
||||
|
||||
# Where to install system configuration files
|
||||
# Where to install system configuration files.
|
||||
# If this is a relative path, it will get installed in `prefix` above
|
||||
#sysconfdir = "/etc"
|
||||
|
||||
|
|
@ -411,9 +423,10 @@ changelog-seen = 2
|
|||
#debug = false
|
||||
|
||||
# Whether to download the stage 1 and 2 compilers from CI.
|
||||
# This is mostly useful for tools; if you have changes to `compiler/` they will be ignored.
|
||||
# This is mostly useful for tools; if you have changes to `compiler/` or `library/` they will be ignored.
|
||||
#
|
||||
# You can set this to "if-unchanged" to only download if `compiler/` has not been modified.
|
||||
# Set this to "if-unchanged" to only download if the compiler and standard library have not been modified.
|
||||
# Set this to `true` to download unconditionally (useful if e.g. you are only changing doc-comments).
|
||||
#download-rustc = false
|
||||
|
||||
# Number of codegen units to use for each compiler invocation. A value of 0
|
||||
|
|
@ -429,10 +442,8 @@ changelog-seen = 2
|
|||
# See https://github.com/rust-lang/rust/issues/83600.
|
||||
#codegen-units-std = codegen-units
|
||||
|
||||
# Whether or not debug assertions are enabled for the compiler and standard
|
||||
# library. Debug assertions control the maximum log level used by rustc. When
|
||||
# enabled calls to `trace!` and `debug!` macros are preserved in the compiled
|
||||
# binary, otherwise they are omitted.
|
||||
# Whether or not debug assertions are enabled for the compiler and standard library.
|
||||
# These can help find bugs at the cost of a small runtime slowdown.
|
||||
#
|
||||
# Defaults to rust.debug value
|
||||
#debug-assertions = rust.debug (boolean)
|
||||
|
|
@ -444,13 +455,11 @@ changelog-seen = 2
|
|||
#debug-assertions-std = rust.debug-assertions (boolean)
|
||||
|
||||
# Whether or not to leave debug! and trace! calls in the rust binary.
|
||||
# Overrides the `debug-assertions` option, if defined.
|
||||
#
|
||||
# Defaults to rust.debug-assertions value
|
||||
#
|
||||
# If you see a message from `tracing` saying
|
||||
# `max_level_info` is enabled and means logging won't be shown,
|
||||
# set this value to `true`.
|
||||
# If you see a message from `tracing` saying "some trace filter directives would enable traces that
|
||||
# are disabled statically" because `max_level_info` is enabled, set this value to `true`.
|
||||
#debug-logging = rust.debug-assertions (boolean)
|
||||
|
||||
# Whether or not overflow checks are enabled for the compiler and standard
|
||||
|
|
@ -477,18 +486,16 @@ changelog-seen = 2
|
|||
#
|
||||
# Note that debuginfo-level = 2 generates several gigabytes of debuginfo
|
||||
# and will slow down the linking process significantly.
|
||||
#
|
||||
# Defaults to 1 if debug is true
|
||||
#debuginfo-level = 0
|
||||
#debuginfo-level = if rust.debug { 1 } else { 0 }
|
||||
|
||||
# Debuginfo level for the compiler.
|
||||
#debuginfo-level-rustc = debuginfo-level
|
||||
#debuginfo-level-rustc = rust.debuginfo-level
|
||||
|
||||
# Debuginfo level for the standard library.
|
||||
#debuginfo-level-std = debuginfo-level
|
||||
#debuginfo-level-std = rust.debuginfo-level
|
||||
|
||||
# Debuginfo level for the tools.
|
||||
#debuginfo-level-tools = debuginfo-level
|
||||
#debuginfo-level-tools = rust.debuginfo-level
|
||||
|
||||
# Debuginfo level for the test suites run with compiletest.
|
||||
# FIXME(#61117): Some tests fail when this option is enabled.
|
||||
|
|
@ -520,6 +527,7 @@ changelog-seen = 2
|
|||
|
||||
# Build a multi-threaded rustc
|
||||
# FIXME(#75760): Some UI tests fail when this option is enabled.
|
||||
# NOTE: This option is NOT SUPPORTED. See #48685.
|
||||
#parallel-compiler = false
|
||||
|
||||
# The default linker that will be hard-coded into the generated
|
||||
|
|
@ -546,7 +554,7 @@ changelog-seen = 2
|
|||
# upstream Rust you need to set this to "". However, note that if you are not
|
||||
# actually compatible -- for example if you've backported patches that change
|
||||
# behavior -- this may lead to miscompilations or other bugs.
|
||||
#description = <none> (string)
|
||||
#description = ""
|
||||
|
||||
# The root location of the musl installation directory. The library directory
|
||||
# will also need to contain libunwind.a for an unwinding implementation. Note
|
||||
|
|
@ -575,14 +583,16 @@ changelog-seen = 2
|
|||
|
||||
# Flag indicating whether git info will be retrieved from .git automatically.
|
||||
# Having the git information can cause a lot of rebuilds during development.
|
||||
# Note: If this attribute is not explicitly set (e.g. if left commented out) it
|
||||
# will default to true if channel = "dev", but will default to false otherwise.
|
||||
#ignore-git = if channel == "dev" { true } else { false }
|
||||
#
|
||||
# FIXME(#76720): this can causes bugs if different compilers reuse the same metadata cache.
|
||||
#ignore-git = if rust.channel == "dev" { true } else { false }
|
||||
|
||||
# When creating source tarballs whether or not to create a source tarball.
|
||||
# Whether to create a source tarball by default when running `x dist`.
|
||||
#
|
||||
# You can still build a source tarball when this is disabled by explicitly passing `x dist rustc-src`.
|
||||
#dist-src = true
|
||||
|
||||
# After building or testing extended tools (e.g. clippy and rustfmt), append the
|
||||
# After building or testing an optional component (e.g. the nomicon or reference), append the
|
||||
# result (broken, compiling, testing) into this JSON file.
|
||||
#save-toolstates = <none> (path)
|
||||
|
||||
|
|
@ -624,11 +634,12 @@ changelog-seen = 2
|
|||
# will make code compile faster at the expense of lower runtime performance.
|
||||
#thin-lto-import-instr-limit = if incremental { 10 } else { LLVM default (currently 100) }
|
||||
|
||||
# Map debuginfo paths to `/rust/$sha/...`, generally only set for releases
|
||||
# Map debuginfo paths to `/rust/$sha/...`.
|
||||
# Useful for reproducible builds. Generally only set for releases
|
||||
#remap-debuginfo = false
|
||||
|
||||
# Link the compiler against `jemalloc`, where on Linux and OSX it should
|
||||
# override the default allocator for rustc and LLVM.
|
||||
# Link the compiler and LLVM against `jemalloc` instead of the default libc allocator.
|
||||
# This option is only tested on Linux and OSX.
|
||||
#jemalloc = false
|
||||
|
||||
# Run tests in various test suites with the "nll compare mode" in addition to
|
||||
|
|
|
|||
|
|
@ -8,9 +8,11 @@ doc-stage = 2
|
|||
# When compiling from source, you usually want all tools.
|
||||
extended = true
|
||||
|
||||
# Most users installing from source want to build all parts of the project from source.
|
||||
[llvm]
|
||||
# Most users installing from source want to build all parts of the project from source, not just rustc itself.
|
||||
download-ci-llvm = false
|
||||
[rust]
|
||||
download-rustc = false
|
||||
|
||||
[dist]
|
||||
# Use better compression when preparing tarballs.
|
||||
|
|
|
|||
Loading…
Reference in New Issue