Auto merge of #123656 - lqd:linker-features, r=petrochenkov

Linker flavors next steps: linker features

This is my understanding of the first step towards `@petrochenkov's` vision for the future of linker flavors, described in https://github.com/rust-lang/rust/pull/119906#issuecomment-1895693162 and the discussion that followed.

To summarize: having `Cc` and `Lld` embedded in linker flavors creates tension about naming, and a combinatorial explosion of flavors for each new linker feature we'd want to use. Linker features are an extension mechanism that is complementary to principal flavors, with benefits described in #119906.

The most immediate use of this flag would be to turn self-contained linking on and off via features instead of flavors. For example, `-Clinker-features=+/-lld` would toggle using lld instead of selecting a precise flavor, and would be "generic" and work cross-platform (whereas linker flavors are currently more tied to targets). Under this scheme, MCP510 is expected to be `-Clink-self-contained=+linker -Zlinker-features=+lld -Zunstable-options` (though for the time being, the original flags using lld-cc flavors still work).

I purposefully didn't add or document CLI support for `+/-cc`, as it would be a noop right now. I only expect that we'd initially want to stabilize `+/-lld` to begin with.

r? `@petrochenkov`

You had requested that minimal churn would be done to the 230 target specs and this does none yet: the linker features are inferred from the flavor since they're currently isomorphic. We of course expect this to change sooner rather than later.

In the future, we can allow targets to define linker features independently from their flavor, and remove the cc and lld components from the flavors to use the features instead, this actually doesn't need to block stabilization, as we discussed.

(Best reviewed per commit)

1 files changed, 35 insertions, 0 deletions

diff --git a/src/doc/unstable-book/src/compiler-flags/linker-features.md b/src/doc/unstable-book/src/compiler-flags/linker-features.md
new file mode 100644
index 00000000000..643fcf7c6d7
--- /dev/null
+++ b/src/doc/unstable-book/src/compiler-flags/linker-features.md
@@ -0,0 +1,35 @@
+# `linker-features`
+
+--------------------
+
+The `-Zlinker-features` compiler flag allows enabling or disabling specific features used during
+linking, and is intended to be stabilized under the codegen options as `-Clinker-features`.
+
+These feature flags are a flexible extension mechanism that is complementary to linker flavors,
+designed to avoid the combinatorial explosion of having to create a new set of flavors for each
+linker feature we'd want to use.
+
+For example, this design allows:
+- default feature sets for principal flavors, or for specific targets.
+- flavor-specific features: for example, clang offers automatic cross-linking with `--target`, which
+  gcc-style compilers don't support. The *flavor* is still a C/C++ compiler, and we don't want to
+  multiply the number of flavors for this use-case. Instead, we can have a single `+target` feature.
+- umbrella features: for example, if clang accumulates more features in the future than just the
+  `+target` above. That could be modeled as `+clang`.
+- niche features for resolving specific issues: for example, on Apple targets the linker flag
+  implementing the `as-needed` native link modifier (#99424) is only possible on sufficiently recent
+  linker versions.
+- still allows for discovery and automation, for example via feature detection. This can be useful
+  in exotic environments/build systems.
+
+The flag accepts a comma-separated list of features, individually enabled (`+features`) or disabled
+(`-features`), though currently only one is exposed on the CLI:
+- `lld`: to toggle using the lld linker, either the system-installed binary, or the self-contained
+  `rust-lld` linker.
+
+As described above, this list is intended to grow in the future.
+
+One of the most common uses of this flag will be to toggle self-contained linking with `rust-lld` on
+and off: `-Clinker-features=+lld -Clink-self-contained=+linker` will use the toolchain's `rust-lld`
+as the linker. Inversely, `-Clinker-features=-lld` would opt out of that, if the current target had
+self-contained linking enabled by default.