note about why stage1/stage2 are different

1 files changed, 9 insertions, 0 deletions

diff --git a/src/doc/rustc-dev-guide/src/how-to-build-and-run.md b/src/doc/rustc-dev-guide/src/how-to-build-and-run.md
index 59c31491e1e..f6c26ddf197 100644
--- a/src/doc/rustc-dev-guide/src/how-to-build-and-run.md
+++ b/src/doc/rustc-dev-guide/src/how-to-build-and-run.md
@@ -62,6 +62,15 @@ internally. The result is the compiling `rustc` is done in stages:
   compiled with the stage0 compiler to produce the stage1 compiler.
   However, it was built with an older compiler (stage0), so to
   optimize the stage1 compiler we go to next stage.
+  - (In theory, the stage1 compiler is functionally identical to the
+    stage2 compiler, but in practice there are subtle differences. In
+    particular, the stage1 compiler itself was built by stage0 and
+    hence not by the source in your working directory: this means that
+    the symbol names used in the compiler source may not match the
+    symbol names that would have been made by the stage1 compiler.
+    This can be important when using dynamic linking (e.g., with
+    derives. Sometimes this means that some tests don't work when run
+    with stage1.)
 - **Stage 2:** we rebuild our stage1 compiler with itself to produce
   the stage2 compiler (i.e. it builds itself) to have all the _latest
   optimizations_.