add documentation on howto build just rustc without libstd to the build system

2 files changed, 19 insertions, 1 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 495d7e46baa..60935770781 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -108,7 +108,8 @@ root.
 There are large number of options accepted by this script to alter the
 configuration used later in the build process. Some options to note:
 
-- `--enable-debug` - Build a debug version of the compiler (disables optimizations)
+- `--enable-debug` - Build a debug version of the compiler (disables optimizations,
+    which speeds up compilation of stage1 rustc)
 - `--enable-optimize` - Enable optimizations (can be used with `--enable-debug`
     to make a debug build with optimizations)
 - `--disable-valgrind-rpass` - Don't run tests with valgrind
@@ -128,6 +129,12 @@ Some common make targets are:
   cases we don't need to build the stage2 compiler, so we can save time by not
   building it. The stage1 compiler is a fully functioning compiler and
   (probably) will be enough to determine if your change works as expected.
+- `make $host/stage1/bin/rustc` - Where $host is a target triple like x86_64-unknown-linux-gnu.
+  This will build just rustc, without libstd. This is the fastest way to recompile after
+  you changed only rustc source code. Note however that the resulting rustc binary
+  won't have a stdlib to link against by default. You can build libstd once with
+  `make rustc-stage1`, rustc will pick it up afterwards. libstd is only guaranteed to
+  work if recompiled, so if there are any issues recompile it.
 - `make check` - build the full compiler & run all tests (takes a while). This
   is what gets run by the continuous integration system against your pull
   request. You should run this before submitting to make sure your tests pass
diff --git a/Makefile.in b/Makefile.in
index 7425e9bd73e..20e2e19305e 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -62,6 +62,8 @@
 #   * tidy - Basic style check, show highest rustc error code and
 #     the status of language and lib features
 #   * rustc-stage$(stage) - Only build up to a specific stage
+#   * $host/stage1/bin/rustc - Only build stage1 rustc, not libstd. For further
+#     information see "Rust recipes for build system success" below.
 #
 # Then mix in some of these environment variables to harness the
 # ultimate power of The Rust Build System.
@@ -93,6 +95,15 @@
 #     // Modifying libstd? Use this command to run unit tests just on your change
 #     make check-stage1-std NO_REBUILD=1 NO_BENCH=1
 #
+#     // Modifying just rustc?
+#     // Compile rustc+libstd once
+#     make rustc-stage1
+#     // From now on use this command to rebuild just rustc and reuse the previously built libstd
+#     // $host is a target triple, eg. x86_64-unknown-linux-gnu
+#     // The resulting binary is located at $host/stage1/bin/rustc.
+#     // If there are any issues with libstd recompile it with the command above.
+#     make $host/stage1/bin/rustc
+#
 #     // Added a run-pass test? Use this to test running your test
 #     make check-stage1-rpass TESTNAME=my-shiny-new-test
 #