Auto merge of rust-lang#119024 - lqd:linker-docs, r=petrochenkov

Document unstable linker flags in the unstable book

This PR:
- removes the unstable linker flavors from the stable documentation
- documents the unstable `-C linker-flavor` values in the unstable book (including the ones previously described as stable)
- documents the unstable `-C link-self-contained` components in the unstable book

I don't know if these have some common reviewers, but if not r? `@petrochenkov` as the most knowledgeable person in this area. Please feel free to reassign, I know that you are quite busy.

Author: bors

src/doc/rustc/src/codegen-options/index.md

@@ -221,7 +221,7 @@ metrics.
 ## link-self-contained
 
 On `windows-gnu`, `linux-musl`, and `wasi` targets, this flag controls whether the
-linker will use libraries and objects shipped with Rust instead or those in the system.
+linker will use libraries and objects shipped with Rust instead of those in the system.
 It takes one of the following values:
 
 * no value: rustc will use heuristic to disable self-contained mode if system has necessary tools.
@@ -249,9 +249,6 @@ flavor. Valid options are:
 * `gcc`: use the `cc` executable, which is typically gcc or clang on many systems.
 * `ld`: use the `ld` executable.
 * `msvc`: use the `link.exe` executable from Microsoft Visual Studio MSVC.
-* `ptx`: use [`rust-ptx-linker`](https://github.com/denzp/rust-ptx-linker)
-  for Nvidia NVPTX GPGPU support.
-* `bpf`: use [`bpf-linker`](https://github.com/alessandrod/bpf-linker) for eBPF support.
 * `wasm-ld`: use the [`wasm-ld`](https://lld.llvm.org/WebAssembly.html)
   executable, a port of LLVM `lld` for WebAssembly.
 * `ld64.lld`: use the LLVM `lld` executable with the [`-flavor darwin`

src/doc/unstable-book/src/compiler-flags/codegen-options.md

@@ -0,0 +1,56 @@
+# Unstable codegen options
+
+All of these options are passed to `rustc` via the `-C` flag, short for "codegen". The flags are
+stable but some of their values are individually unstable, and also require using `-Z
+unstable-options` to be accepted.
+
+## linker-flavor
+
+In addition to the stable set of linker flavors, the following unstable values also exist:
+- `ptx`: use [`rust-ptx-linker`](https://github.com/denzp/rust-ptx-linker)
+  for Nvidia NVPTX GPGPU support.
+- `bpf`: use [`bpf-linker`](https://github.com/alessandrod/bpf-linker) for eBPF support.
+
+Additionally, a set of more precise linker flavors also exists, for example allowing targets to
+declare that they use the LLD linker by default. The following values are currently unstable, and
+the goal is for them to become stable, and preferred in practice over the existing stable values:
+- `gnu`: unix-like linker with GNU extensions
+- `gnu-lld`: `gnu` using LLD
+- `gnu-cc`: `gnu` using a C/C++ compiler as the linker driver
+- `gnu-lld-cc`: `gnu` using LLD and a C/C++ compiler as the linker driver
+- `darwin`: unix-like linker for Apple targets
+- `darwin-lld`: `darwin` using LLD
+- `darwin-cc`: `darwin` using a C/C++ compiler as the linker driver
+- `darwin-lld-cc`: `darwin` using LLD and a C/C++ compiler as the linker driver
+- `wasm-lld`: unix-like linker for Wasm targets, with LLD
+- `wasm-lld-cc`: unix-like linker for Wasm targets, with LLD and a C/C++ compiler as the linker
+  driver
+- `unix`: basic unix-like linker for "any other Unix" targets (Solaris/illumos, L4Re, MSP430, etc),
+  not supported with LLD.
+- `unix-cc`: `unix` using a C/C++ compiler as the linker driver
+- `msvc-lld`: MSVC-style linker for Windows and UEFI, with LLD
+- `em-cc`: emscripten compiler frontend, similar to `wasm-lld-cc` with a different interface
+
+## link-self-contained
+
+This flag generally controls whether the linker will use libraries and objects shipped with Rust
+instead of those in the system. The stable boolean values for this flag are coarse-grained
+(everything or nothing), but there exists a set of unstable values with finer-grained control,
+`-Clink-self-contained` can accept a comma-separated list of components, individually enabled
+(`+component`) or disabled (`-component`):
+- `crto`: CRT objects (e.g. on `windows-gnu`, `musl`, `wasi` targets)
+- `libc`: libc static library (e.g. on `musl`, `wasi` targets)
+- `unwind`: libgcc/libunwind (e.g. on `windows-gnu`, `fuchsia`, `fortanix`, `gnullvm` targets)
+- `linker`: linker, dlltool, and their necessary libraries (e.g. on `windows-gnu` and for
+  `rust-lld`)
+- `sanitizers`: sanitizer runtime libraries
+- `mingw`: other MinGW libs and Windows import libs
+
+Out of the above self-contained linking components, `linker` is the only one currently implemented
+(beyond parsing the CLI options).
+
+It refers to the LLD linker, built from the same LLVM revision used by rustc (named `rust-lld` to
+avoid naming conflicts), that is distributed via `rustup` with the compiler (and is used by default
+for the wasm targets). One can also opt-in to use it by combining this flag with an appropriate
+linker flavor: for example, `-Clinker-flavor=gnu-lld-cc -Clink-self-contained=+linker` will use the
+toolchain's `rust-lld` as the linker.