From d34a247ab824bae40b0c5665fb16516146483630 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Sun, 20 Aug 2023 20:15:10 -0700
Subject: [PATCH] Document alt builds

---
 guide/src/SUMMARY.md |  1 +
 guide/src/alt.md     | 29 +++++++++++++++++++++++++++++
 2 files changed, 30 insertions(+)
 create mode 100644 guide/src/alt.md

diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md
index cca7816..1aa6ed3 100644
--- a/guide/src/SUMMARY.md
+++ b/guide/src/SUMMARY.md
@@ -8,6 +8,7 @@
 - [Bisection boundaries](boundaries.md)
 - [Rustup toolchains](rustup.md)
 - [Git bisect a custom build](git-bisect.md)
+- [Alt builds](alt.md)
 - [Examples](examples/index.md)
     - [Checking diagnostics](examples/diagnostics.md)
     - [Scripting on Windows](examples/windows-scripting.md)
diff --git a/guide/src/alt.md b/guide/src/alt.md
new file mode 100644
index 0000000..106cb63
--- /dev/null
+++ b/guide/src/alt.md
@@ -0,0 +1,29 @@
+# Alt builds
+
+Each commit also generates what are called "alt" builds.
+These are builds of rustc with some different options set.
+As of August 2023, these include:
+
+* `rust.parallel-compiler`
+* `llvm.assertions`
+* `rust.verify-llvm-ir`
+
+For more information on these settings, see the [`config.toml` docs].
+These alt settings are defined in [`ci/run.sh`].
+
+Alt builds are only available for a few targets.
+Look for the `-alt` builds in [`ci.yml`].
+
+This can be useful if you are bisecting an LLVM issue.
+With LLVM assertions enabled, alt builds have checks that can help identify broken assumptions.
+
+Alt builds are only made for commit builds, and not nightly releases.
+You will need to specify `--by-commit` (or use a hash in the `--start` or `--end` flags) to only use commit builds.
+
+```sh
+cargo bisect-rustc --alt --by-commit
+```
+
+[`config.toml` docs]: https://github.com/rust-lang/rust/blob/master/config.example.toml
+[`ci/run.sh`]: https://github.com/rust-lang/rust/blob/c0b6ffaaea3ebdf5f7a58fc4cf7ee52c91077fb9/src/ci/run.sh#L99-L105
+[`ci.yml`]: https://github.com/rust-lang/rust/blob/HEAD/src/ci/github-actions/ci.yml