rustbuild: Document many more parts of the build

This commit expands the bootstrap build system's `README.md` as well as ensuring
that all API documentation is present and up-to-date. Additionally a new
`config.toml.example` file is checked in with commented out versions of all
possible configuration values.

1 files changed, 10 insertions, 15 deletions

diff --git a/src/bootstrap/rustc.rs b/src/bootstrap/rustc.rs
index 1ebf27b51ad..99e16035d1d 100644
--- a/src/bootstrap/rustc.rs
+++ b/src/bootstrap/rustc.rs
@@ -29,7 +29,6 @@ extern crate bootstrap;
 
 use std::env;
 use std::ffi::OsString;
-use std::path::PathBuf;
 use std::process::Command;
 
 fn main() {
@@ -54,16 +53,9 @@ fn main() {
     cmd.args(&args)
        .arg("--cfg").arg(format!("stage{}", env::var("RUSTC_STAGE").unwrap()));
 
-    if target.is_none() {
-        // Build scripts are always built with the snapshot compiler, so we need
-        // to be sure to set up the right path information for the OS dynamic
-        // linker to find the libraries in question.
-        if let Some(p) = env::var_os("RUSTC_SNAPSHOT_LIBDIR") {
-            let mut path = bootstrap::dylib_path();
-            path.insert(0, PathBuf::from(p));
-            cmd.env(bootstrap::dylib_path_var(), env::join_paths(path).unwrap());
-        }
-    } else {
+    if let Some(target) = target {
+        // The stage0 compiler has a special sysroot distinct from what we
+        // actually downloaded, so we just always pass the `--sysroot` option.
         cmd.arg("--sysroot").arg(env::var_os("RUSTC_SYSROOT").unwrap());
 
         // When we build Rust dylibs they're all intended for intermediate
@@ -71,20 +63,23 @@ fn main() {
         // linking all deps statically into the dylib.
         cmd.arg("-Cprefer-dynamic");
 
+        // Help the libc crate compile by assisting it in finding the MUSL
+        // native libraries.
         if let Some(s) = env::var_os("MUSL_ROOT") {
             let mut root = OsString::from("native=");
             root.push(&s);
             root.push("/lib");
             cmd.arg("-L").arg(&root);
         }
+
+        // Pass down extra flags, commonly used to configure `-Clinker` when
+        // cross compiling.
         if let Ok(s) = env::var("RUSTC_FLAGS") {
             cmd.args(&s.split(" ").filter(|s| !s.is_empty()).collect::<Vec<_>>());
         }
-    }
 
-    // Set various options from config.toml to configure how we're building
-    // code.
-    if let Some(target) = target {
+        // Set various options from config.toml to configure how we're building
+        // code.
         if env::var("RUSTC_DEBUGINFO") == Ok("true".to_string()) {
             cmd.arg("-g");
         }