A few small improvements to the contributing docs

CONTRIBUTING.md

@@ -112,14 +112,17 @@ There are large number of options provided in this config file that will alter t
 configuration used in the build process. Some options to note:
 
 #### `[llvm]`:
+- `assertions = true` = This enables LLVM assertions, which makes LLVM misuse cause an assertion failure instead of weird misbehavior. This also slows down the compiler's runtime by ~20%.
 - `ccache = true` - Use ccache when building llvm
 
 #### `[build]`:
 - `compiler-docs = true` - Build compiler documentation
 
 #### `[rust]`:
-- `debuginfo = true` - Build a compiler with debuginfo
+- `debuginfo = true` - Build a compiler with debuginfo. Makes building rustc slower, but then you can use a debugger to debug `rustc`.
-- `optimize = false` - Disable optimizations to speed up compilation of stage1 rust
+- `debuginfo-lines = true` - An alternative to `debuginfo = true` that doesn't let you use a debugger, but doesn't make building rustc slower and still gives you line numbers in backtraces.
+- `debug-assertions = true` - Makes the log output of `debug!` work.
+- `optimize = false` - Disable optimizations to speed up compilation of stage1 rust, but makes the stage1 compiler x100 slower.
 
 For more options, the `config.toml` file contains commented out defaults, with
 descriptions of what each option will do.
@@ -273,6 +276,27 @@ build, you'll need to build rustdoc specially, since it's not normally built in
 stage 1. `python x.py build --stage 1 src/libstd src/tools/rustdoc` will build
 rustdoc and libstd, which will allow rustdoc to be run with that toolchain.)
 
+### Out-of-tree builds
+[out-of-tree-builds]: #out-of-tree-builds
+
+Rust's `x.py` script fully supports out-of-tree builds - it looks for
+the Rust source code from the directory `x.py` was found in, but it
+reads the `config.toml` configuration file from the directory it's
+run in, and places all build artifacts within a subdirectory named `build`.
+
+This means that if you want to do an out-of-tree build, you can just do it:
+```
+$ cd my/build/dir
+$ cp ~/my-config.toml config.toml # Or fill in config.toml otherwise
+$ path/to/rust/x.py build
+...
+$ # This will use the Rust source code in `path/to/rust`, but build
+$ # artifacts will now be in ./build
+```
+
+It's absolutely fine to have multiple build directories with different
+`config.toml` configurations using the same code.
+
 ## Pull Requests
 [pull-requests]: #pull-requests
 

src/test/COMPILER_TESTS.md

@@ -35,20 +35,24 @@ The error levels that you can have are:
 ## Summary of Header Commands
 
 Header commands specify something about the entire test file as a
-whole, instead of just a few lines inside the test.
+whole. They are normally put right after the copyright comment, e.g.:
+
+```Rust
+// Copyright blah blah blah
+// except according to those terms.
+
+// ignore-test This doesn't actually work
+```
+
+### Ignoring tests
+
+These are used to ignore the test in some situations, which means the test won't
+be compiled or run.
 
 * `ignore-X` where `X` is a target detail or stage will ignore the test accordingly (see below)
 * `ignore-pretty` will not compile the pretty-printed test (this is done to test the pretty-printer, but might not always work)
 * `ignore-test` always ignores the test
-* `ignore-lldb` and `ignore-gdb` will skip the debuginfo tests
+* `ignore-lldb` and `ignore-gdb` will skip a debuginfo test on that debugger.
-* `min-{gdb,lldb}-version`
-* `should-fail` indicates that the test should fail; used for "meta testing",
-  where we test the compiletest program itself to check that it will generate
-  errors in appropriate scenarios. This header is ignored for pretty-printer tests.
-* `gate-test-X` where `X` is a feature marks the test as "gate test" for feature X.
-  Such tests are supposed to ensure that the compiler errors when usage of a gated
-  feature is attempted without the proper `#![feature(X)]` tag.
-  Each unstable lang feature is required to have a gate test.
 
 Some examples of `X` in `ignore-X`:
 
@@ -58,6 +62,22 @@ Some examples of `X` in `ignore-X`:
 * Pointer width: `32bit`, `64bit`.
 * Stage: `stage0`, `stage1`, `stage2`.
 
+### Other Header Commands
+
+* `min-{gdb,lldb}-version`
+* `min-llvm-version`
+* `must-compile-successfully` for UI tests, indicates that the test is supposed
+  to compile, as opposed to the default where the test is supposed to error out.
+* `compile-flags` passes extra command-line args to the compiler,
+  e.g. `compile-flags -g` which forces debuginfo to be enabled.
+* `should-fail` indicates that the test should fail; used for "meta testing",
+  where we test the compiletest program itself to check that it will generate
+  errors in appropriate scenarios. This header is ignored for pretty-printer tests.
+* `gate-test-X` where `X` is a feature marks the test as "gate test" for feature X.
+  Such tests are supposed to ensure that the compiler errors when usage of a gated
+  feature is attempted without the proper `#![feature(X)]` tag.
+  Each unstable lang feature is required to have a gate test.
+
 ## Revisions
 
 Certain classes of tests support "revisions" (as of the time of this
@@ -109,6 +129,12 @@ fails, we will print out the current output, but it is also saved in
 printed as part of the test failure message), so you can run `diff` and
 so forth.
 
+Normally, the test-runner checks that UI tests fail compilation. If you want
+to do a UI test for code that *compiles* (e.g. to test warnings, or if you
+have a collection of tests, only some of which error out), you can use the
+`// must-compile-successfully` header command to have the test runner instead
+check that the test compiles successfully.
+
 ### Editing and updating the reference files
 
 If you have changed the compiler's output intentionally, or you are