Add section about building an optimized version of rustc

src/SUMMARY.md

@@ -14,6 +14,7 @@
     - [Building Documentation](./building/compiler-documenting.md)
     - [Rustdoc overview](./rustdoc.md)
     - [Adding a new target](./building/new-target.md)
+    - [Optimized build](./building/optimized-build.md)
 - [Testing the compiler](./tests/intro.md)
     - [Running tests](./tests/running.md)
         - [Testing with Docker](./tests/docker.md)

src/building/optimized-build.md

@@ -0,0 +1,124 @@
+# Optimized build of the compiler
+
+<!-- toc -->
+
+There are multiple additional build configuration options and techniques that can used to compile a build of `rustc`
+that is as optimized as possible (for example when building `rustc` for a Linux distribution). The status of these
+configuration options for various Rust targets is tracked [here]. This page describes how you can use these approaches
+when building `rustc` yourself.
+
+[here]: /~https://github.com/rust-lang/rust/issues/103595
+
+## Link-time optimization
+
+Link-time optimization is a powerful compiler technique that can increase program performance. To enable (Thin-)LTO when
+building `rustc`, set the `rust.lto` config option to `"thin"` in `config.toml`:
+
+```toml
+[rust]
+lto = "thin"
+```
+
+> Note that LTO for `rustc` is currently supported and tested only for the `x86_64-unknown-linux-gnu` target. Other
+> targets *may* work, but no guarantees are provided. Notably, LTO optimized `rustc` currently produces
+> [miscompilations] on Windows.
+
+[miscompilations]: /~https://github.com/rust-lang/rust/issues/109114
+
+Enabling LTO on Linux has [produced] speed-ups by up to 10%.
+
+[produced]: /~https://github.com/rust-lang/rust/pull/101403#issuecomment-1288190019
+
+## Memory allocator
+
+Using a different memory allocator for `rustc` can provide significant performance benefits. If you want to enable
+the `jemalloc` allocator, you can set the `rust.jemalloc` option to `true` in `config.toml`:
+
+```toml
+[rust]
+jemalloc = true
+```
+
+> Note that this option is currently only supported for Linux and macOS targets.
+
+## Codegen units
+
+Reducing the amount of codegen units per `rustc` crate can produce a faster build of the compiler. You can modify the
+number of codegen units for `rustc` and `libstd` in `config.toml` with the following options:
+
+```toml
+[rust]
+codegen-units = 1
+codegen-units-std = 1
+```
+
+## Instruction set
+
+By default, `rustc` is compiled for a generic (and conservative) instruction set architecture (depending on the selected
+target), to make it support as many CPUs as possible. If you want to compile `rustc` for a specific instruction
+set architecture, you can set the `target_cpu` compiler option in `RUSTFLAGS`:
+
+```bash
+$ RUSTFLAGS="-C target_cpu=x86-64-v3" x.py build ...
+```
+
+If you also want to compile LLVM for a specific instruction set, you can set `llvm` flags in `config.toml`:
+
+```toml
+[llvm]
+cxxflags = "-march=x86-64-v3"
+cflags = "-march=x86-64-v3"
+```
+
+## Profile-guided optimization
+
+Applying profile-guided optimizations (or more generally, feedback-directed optimizations) can produce a large increase
+to `rustc` performance, by up to 25%. However, these techniques are not simply enabled by a configuration option,
+but rather they require a complex build workflow that compiles `rustc` multiple times and profiles it on selected
+benchmarks.
+
+There is a tool called `opt-dist` that is used to optimize `rustc` with [PGO] (profile-guided optimizations) and [BOLT]
+(a post-link binary optimizer) for builds distributed to end users. You can examine the tool, which is located
+in `src/tools/opt-dist`, and build a custom PGO build workflow based on it, or try to use it directly. Note that the
+tool is currently quite hardcoded to the way we use it in Rust's continuous integration workflows, and it might require
+some custom changes to make it work in a different environment.
+
+[PGO]: https://doc.rust-lang.org/rustc/profile-guided-optimization.html
+
+[BOLT]: /~https://github.com/llvm/llvm-project/blob/main/bolt/README.md
+
+To use the tool, you will need to provide some external dependencies:
+
+- A Python3 interpreter (for executing `x.py`).
+- Compiled LLVM toolchain, with the `llvm-profdata` binary. Optionally, if you want to use BOLT, the `llvm-bolt` and
+  `merge-fdata` binaries have to be available in the toolchain.
+- Downloaded [Rust benchmark suite]. (You can also let the tool download it itself, if you implement a custom
+  environment, see below).
+
+These dependencies are provided to `opt-dist` by an implementation of the [`Environment`] trait. You can either
+implement the trait for your custom environment, by providing paths to these dependencies in its methods, or reuse one
+of the existing implementations (currently, there is an implementation for Linux and Windows). If you want your
+environment to support BOLT, return `true` from the `supports_bolt` method.
+
+Here is an example of how can `opt-dist` be used with the default Linux environment (it assumes that you execute the
+following commands on a Linux system):
+
+1. Build the tool with the following command:
+    ```bash
+    $ python3 x.py build tools/opt-dist
+    ```
+2. Run the tool with the `PGO_HOST` environment variable set to the 64-bit Linux target:
+    ```bash
+    $ PGO_HOST=x86_64-unknown-linux-gnu ./build/host/stage0-tools-bin/opt-dist
+    ```
+   Note that the default Linux environment expects several hardcoded paths to exist:
+    - `/checkout` should contain a checkout of the Rust compiler repository that will be compiled.
+    - `/rustroot` should contain the compiled LLVM toolchain (containing BOLT).
+    - A Python 3 interpreter should be available under the `python3` binary.
+    - `/tmp/rustc-perf` should contain a downloaded checkout of the Rust benchmark suite.
+
+You can modify `LinuxEnvironment` (or implement your own) to override these paths.
+
+[`Environment`]: /~https://github.com/rust-lang/rust/blob/65e468f9c259749c210b1ae8972bfe14781f72f1/src/tools/opt-dist/src/environment/mod.rs#L8-L7
+
+[Rust benchmark suite]: /~https://github.com/rust-lang/rustc-perf