From: Felix S. Klock II Date: Mon, 8 Oct 2018 13:43:53 +0000 (+0200) Subject: Added text explaining the (new) relative roles of `optimize`+`debug` X-Git-Url: https://git.lizzy.rs/?a=commitdiff_plain;h=40e20e288d0f928c25bc74c14d74227c4d5c7182;p=rust.git Added text explaining the (new) relative roles of `optimize`+`debug` and to briefly touch on the theory of debugging rustc versus the practice of such. --- diff --git a/config.toml.example b/config.toml.example index 66eaab236f7..c840be9f5d2 100644 --- a/config.toml.example +++ b/config.toml.example @@ -243,19 +243,36 @@ # ============================================================================= [rust] -# Indicates that the build should be optimized for debugging Rust. Note that -# this is typically not what you want as it takes an incredibly large amount of -# time to have a debug-mode rustc compile any code (notably libstd). If this -# value is set to `true` it will affect a number of configuration options below -# as well, if unconfigured. -#debug = false - -# Whether or not to optimize the compiler and standard library +# Whether or not to optimize the compiler and standard library. +# # Note: the slowness of the non optimized compiler compiling itself usually # outweighs the time gains in not doing optimizations, therefore a -# full bootstrap takes much more time with optimize set to false. +# full bootstrap takes much more time with `optimize` set to false. #optimize = true +# Indicates that the build should be configured for debugging Rust. A +# `debug`-enabled compiler and standard library will be somewhat +# slower (due to e.g. checking of debug assertions) but should remain +# usable. +# +# Note: If this value is set to `true`, it will affect a number of +# configuration options below as well, if they have been left +# unconfigured in this file. +# +# Note: changes to the `debug` setting do *not* affect `optimize` +# above. In theory, a "maximally debuggable" environment would +# set `optimize` to `false` above to assist the introspection +# facilities of debuggers like lldb and gdb. To recreate such an +# environment, explicitly set `optimize` to `false` and `debug` +# to `true`. In practice, everyone leaves `optimize` set to +# `true`, because an unoptimized rustc with debugging +# enabled becomes *unusably slow* (e.g. rust-lang/rust#24840 +# reported a 25x slowdown) and bootstrapping the supposed +# "maximally debuggable" environment (notably libstd) takes +# hours to build. +# +#debug = false + # Number of codegen units to use for each compiler invocation. A value of 0 # means "the number of cores on this machine", and 1+ is passed through to the # compiler.