add some more comments

config.example.toml

@@ -329,7 +329,11 @@ changelog-seen = 2
 #profiler = false
 
 # Use the optimized LLVM C intrinsics for `compiler_builtins`, rather than Rust intrinsics.
-# Requires the LLVM submodule to be managed by bootstrap (i.e. not external).
+# Requires the LLVM submodule to be managed by bootstrap (i.e. not external) so that `compiler-rt`
+# sources are available.
+#
+# Setting this to `false` generates slower code, but removes the requirement for a C toolchain in
+# order to run `x check`.
 #optimized-compiler-builtins = false
 
 # Indicates whether the native libraries linked into Cargo will be statically

src/bootstrap/compile.rs

@@ -354,11 +354,14 @@ pub fn std_cargo(builder: &Builder<'_>, target: TargetSelection, stage: u32, car
         // But, the user could still decide to manually use an in-tree submodule.
         //
         // Using system llvm is not supported.
+        // FIXME: is that restriction really required? I don't *think* we need the LLVM used by
+        // compiler-builtins to match the one linked to rustc, but there's a comment in its build
+        // script that makes me nervous: https://github.com/rust-lang/compiler-builtins/blob/31ee4544dbe47903ce771270d6e3bea8654e9e50/build.rs#L575-L579
         builder.update_submodule(&Path::new("src").join("llvm-project"));
         let compiler_builtins_root = builder.src.join("src/llvm-project/compiler-rt");
         if !compiler_builtins_root.exists() || builder.is_system_llvm(target) {
             panic!(
-                "needed LLVM sources available to build `compiler-rt`, but they weren't present; consider enabling `build.submodules = true`, disabling `optimized-compiler-builtins`, or unsetting `llvm-config`"
+                "need LLVM sources available to build `compiler-rt`, but they weren't present; consider enabling `build.submodules = true`, disabling `optimized-compiler-builtins`, or unsetting `llvm-config`"
             );
         }
         // Note that `libprofiler_builtins/build.rs` also computes this so if