Compiletest docs for recently-added features (#1994)

* Docs for `needs-forced-clang-based-tests` (was `needs-matching-clang`)

* Docs for `aux-codegen-backend`

* Docs for `{{sysroot-base}}` and `{{target-linker}}`

src/tests/compiletest.md

@@ -516,11 +516,12 @@ only running the main `coverage` suite.
 ## Building auxiliary crates
 
 It is common that some tests require additional auxiliary crates to be compiled.
-There are three [headers](headers.md) to assist with that:
+There are multiple [headers](headers.md) to assist with that:
 
 * `aux-build`
 * `aux-crate`
 * `aux-bin`
+* `aux-codegen-backend`
 
 `aux-build` will build a separate crate from the named source file.
 The source file should be in a directory called `auxiliary` beside the test file.
@@ -549,6 +550,10 @@ This is similar to how Cargo does dependency renaming.
 library. The binary will be available in `auxiliary/bin` relative to the working
 directory of the test.
 
+`aux-codegen-backend` is similar to `aux-build`, but will then pass the compiled
+dylib to `-Zcodegen-backend` when building the main file. This will only work
+for tests in `tests/ui-fulldeps`, since it requires the use of compiler crates.
+
 ### Auxiliary proc-macro
 
 If you want a proc-macro dependency, then there currently is some ceremony

src/tests/headers.md

@@ -63,6 +63,8 @@ found in [`header.rs`] from the compiletest source.
 * [Building auxiliary crates](compiletest.md#building-auxiliary-crates)
     * `aux-build`
     * `aux-crate`
+    * `aux-bin`
+    * `aux-codegen-backend`
 * [Pretty-printer](compiletest.md#pretty-printer-tests) headers
     * `pretty-compare-only`
     * `pretty-expanded`
@@ -173,11 +175,12 @@ The following header commands will check LLVM support:
 * `ignore-llvm-version: 7.0 - 9.9.9` — ignores LLVM versions in a range (inclusive)
 * `needs-llvm-components: powerpc` — ignores if the specific LLVM component was not built.
   Note: The test will fail on CI (when `COMPILETEST_REQUIRE_ALL_LLVM_COMPONENTS` is set) if the component does not exist.
-* `needs-matching-clang` — ignores if the version of clang does not match the
+* `needs-forced-clang-based-tests` —
-  LLVM version of rustc.
+  test is ignored unless the environment variable `RUSTBUILD_FORCE_CLANG_BASED_TESTS`
-  These tests are always ignored unless a special environment variable,
+  is set, which enables building clang alongside LLVM
-  `RUSTBUILD_FORCE_CLANG_BASED_TESTS`, is set
+  - This is only set in one CI job ([`x86_64-gnu-debug`]), which only runs a tiny
-  (which is only done in one CI job [`x86_64-gnu-debug`]).
+    subset of `run-make` tests. Other tests with this header will not run at all,
+    which is usually not what you want.
 
 See also [Debuginfo tests](compiletest.md#debuginfo-tests) for headers for
 ignoring debuggers.
@@ -280,6 +283,11 @@ described below:
 - `{{build-base}}`: The base directory where the test's output goes. This is
   equivalent to `$TEST_BUILD_DIR` for [output normalization].
   - Example: `/path/to/rust/build/x86_64-unknown-linux-gnu/test/ui`
+- `{{sysroot-base}}`: Path of the sysroot directory used to build the test.
+  - Mainly intended for `ui-fulldeps` tests that run the compiler via API.
+- `{{target-linker}}`: Linker that would be passed to `-Clinker` for this test,
+  or blank if no linker override is active.
+  - Mainly intended for `ui-fulldeps` tests that run the compiler via API.
 - `{{target}}`: The target the test is compiling for
   - Example: `x86_64-unknown-linux-gnu`