Auto merge of #140525 - lqd:stabilize-lld, r=petrochenkov

Use lld by default on `x86_64-unknown-linux-gnu` stable

This PR and stabilization report is joint work with `@Kobzol.`

#### Use LLD on `x86_64-unknown-linux-gnu` by default, and stabilize `-Clinker-features=-lld` and `-Clink-self-contained=-linker`

This PR proposes making LLD the default linker on the `x86_64-unknown-linux-gnu` target for the artifacts we distribute, and also stabilizing the `-Clinker-features=-lld` and `-Clink-self-contained=-linker` codegen options to make it possible to opt out.

LLD has been used as the default linker on nightly and CI on this target since May 2024 ([PR](https://github.com/rust-lang/rust/pull/124129), [blog post](https://blog.rust-lang.org/2024/05/17/enabling-rust-lld-on-linux.html)), and it seems like it is working fine, so we would like to propose stabilizing it.

The main motivation for using LLD instead of the default BFD linker is improving [compilation times](https://perf.rust-lang.org/compare.html?start=b3e117044c7f707293edc040edb93e7ec5f7040a&end=baed03c51a68376c1789cc373581eea0daf89967&stat=instructions%3Au&tab=compile). For example, in the linked benchmark, it makes incremental recompilation of `ripgrep` in `debug` more than twice faster. Another benefit is that Rust compilation becomes more consistent and self-contained, because we will use a known version of the LLD linker, rather than "whatever GNU ld version is on the user's system".

Due to the performance benefit being so huge, many people already opt into using LLD (or other fast linkers, such as mold) using various approaches ([1](https://github.com/search?type=code&q=%2Flinker-flavor%5B%3D+%5Dgnu-lld-cc%2F), [2](https://github.com/search?type=code&q=%2Flinker-features%5B%3D+%5D%5C%2Blld%2F), [3](https://github.com/search?type=code&q=language%3Atoml+%22-fuse-ld%3Dlld%22), [4](https://github.com/search?type=code&q=language%3Arust+%22-fuse-ld%3Dlld%22)). By making LLD the default linker on the `x86_64-unknown-linux-gnu` target, we will be able to speed up Rust compilation out of the box, without users having to opt in or know about it.

> You can find an extended version of this stabilization report which includes analysis of crater results and more data [here](https://hackmd.io/tFDifkUcSLGoHPBRIl0z8w?view).

## What is being stabilized
- `rust-lld` being used as the default linker on the `x86_64-unknown-linux-gnu` target.
    - Note that `rust-lld` is being enabled by default in the compiler artifacts distributed by our CI/rustup. It is still possible to use the system linker by default using `rust.lld = false` in `bootstrap.toml`, which can be useful e.g. for some Linux distros that might not want to use the LLD we distribute.
    - This is done by activating the LLD linker feature and using the self-contained linker on that target. Both of which are also usable on the CLI, if some opt outs are necessary, as described below.
- `-Clinker-features=-lld` on the `x86_64-unknown-linux-gnu` target. This codegen option tells rustc to disable using the LLD linker.
    - Note that other options for this codegen flag (`cc`) remain unstable.
    - Note that only the opt-out is being stabilized, and only for `x86_64-unknown-linux-gnu`: opting in, or using the flag on other targets would still need to pass `-Zunstable-options`.
    - This flag is being stabilized so that users can opt out of LLD on stable, which would it turn also opt out of using the self-contained linker (since it's an LLD).
- `-Clink-self-contained=-linker`. This codegen option tells rustc to use the self-contained linker. It's not particularly useful to turn it on by itself, but when enabled and combined with `-Clinker-features=+lld`, rustc will use the `rust-lld` linker wrapper shipped with the compiler toolchain, instead of some `lld` binary that the linker driver will find in the `PATH`.
    - Note that other options for this codegen flag (other than the previously stable `y/yes/n/no`).
    - Note that only the opt-out is being stabilized, and only for `x86_64-unknown-linux-gnu`: opting in, or using this flag on other targets would still need to pass `-Zunstable-options`.
    - This flag is being stabilized so that users can opt out of using self-contained linking on stable. Doing this would then fall back to using the system `lld`.

To opt out of using LLD, `RUSTFLAGS="-Clinker-features=-lld"` would be used. To opt out of using `rust-lld`, falling back to the LLD installed on the system, `RUSTFLAGS="-Clink-self-contained=-linker"` would be used.

## Tests

When enabling `rust-lld` on nightly, we also switched x64 linux to use it at stage >= 1, meaning that all tests have been running with lld since May 2024, on CI as well as contributors' machines. (Post opt-dist tests also had been using it when running their test subset earlier than that).

There are also a few tests dedicated to the CLI behavior, or ensuring the default linker is indeed the one we expect:

- [link-self-contained-consistency](https://github.com/rust-lang/rust/blob/1117bc1e6ce049495b0044dfe756afafc817d2d7/tests/ui/linking/link-self-contained-consistency.rs): Checks that `-Clink-self-contained` options are not inconsistent (i.e. that passing both `+linker` and `-linker` is an error).
- [link-self-contained-unstable](https://github.com/rust-lang/rust/blob/1117bc1e6ce049495b0044dfe756afafc817d2d7/tests/ui/linking/link-self-contained-unstable.rs): Checks that only the `-linker` and `y/yes/n/no` options for `-Clink-self-contained` are stable.
- [linker-features-unstable-cc](https://github.com/rust-lang/rust/blob/1117bc1e6ce049495b0044dfe756afafc817d2d7/tests/ui/linking/linker-features-unstable-cc.rs): Checks that only the non-lld options of `-Clinker-features` are unstable.
- [linker-features-lld-disallowed](https://github.com/rust-lang/rust/blob/1117bc1e6ce049495b0044dfe756afafc817d2d7/tests/ui/linking/linker-features-lld-disallowed.rs): Checks that `-Clinker-features=-lld` is only stable on `x86_64-unknown-linux-gnu`.
- [link-self-contained-linker-disallowed](https://github.com/rust-lang/rust/blob/1117bc1e6ce049495b0044dfe756afafc817d2d7/tests/ui/linking/link-self-contained-linker-disallowed.rs): Checks that `-Clink-self-contained=-linker` is only stable on `x86_64-unknown-linux-gnu`.
- [no-gc-encapsulation-symbols](https://github.com/rust-lang/rust/blob/1117bc1e6ce049495b0044dfe756afafc817d2d7/tests/ui/linking/no-gc-encapsulation-symbols.rs): Checks that that linker encapsulation symbols are not garbage collected by LLD, so that crates like [linkme](https://github.com/dtolnay/linkme) still work.
- [rust-lld](https://github.com/rust-lang/rust/blob/1117bc1e6ce049495b0044dfe756afafc817d2d7/tests/run-make/rust-lld): Checks that LLD is actually used when enabled with `-Clinker-features=+lld` and `-Clink-self-contained=+linker`.
- [rust-lld-x86_64-unknown-linux-gnu](https://github.com/rust-lang/rust/blob/1117bc1e6ce049495b0044dfe756afafc817d2d7/tests/run-make/rust-lld-x86_64-unknown-linux-gnu): Checks that LLD is used by default on `x86_64-unknown-linux-gnu` when the bootstrap `rust.lld` config option is `true`.
- [rust-lld-x86_64-unknown-linux-gnu-dist](https://github.com/rust-lang/rust/blob/1117bc1e6ce049495b0044dfe756afafc817d2d7/tests/run-make/rust-lld-x86_64-unknown-linux-gnu-dist): Dist test that checks that our distributed `x86_64-unknown-linux-gnu` archives actually use LLD by default.

## Ecosystem impact
As already stated, LLD has been used as the default linker on x64 Linux on nightly for almost a year, and we haven't seen any blockers to stabilization in that time. There were a handful of issues reported, these are discussed later below.

Furthermore, two crater runs ([November 2023](https://crater-reports.s3.amazonaws.com/pr-117684-2/index.html), [February 2025](https://crater-reports.s3.amazonaws.com/pr-137044-3/index.html)), were performed to test the impact of using LLD as the default linker. A triage of the earlier crater run was previously done [here](https://hackmd.io/OAJxlxc6Te6YUot9ftYSKQ), but all the important findings from both crater runs are reported below.

Below is a list of compatibility differences between BFD and LLD that we have encountered. There is a more thorough list of differences in [this post](https://maskray.me/blog/2020-12-19-lld-and-gnu-linker-incompatibilities) from the current LLD maintainer. From that post, "99.9% pieces of software work with ld.lld without a change".

---

### `.ctors/.dtors` sections
[#128286](https://github.com/rust-lang/rust/issues/128286) reported an issue where LLD was unable to link certain CUDA library was using these sections that were using the `.ctors/.dtors` ELF sections. These were deprecated a long time ago (https://gcc.gnu.org/bugzilla/show_bug.cgi?id=46770), replaced with a more modern `.init_array/.fini_array` sections. LLD doesn't (and won't) support these sections ([1](https://github.com/llvm/llvm-project/issues/68071), [2](https://github.com/llvm/llvm-project/issues/30572)), so if they appear in input object files, the linked artifact might produce incorrect behavior, because e.g. some global variables might not get initialized properly.

However, the usage of `.ctors/.dtors` should be very rare in practice. We have performed a [crater run](https://github.com/rust-lang/rust/pull/137044) to test this. It has identified only 8 crates where the `.ctors/.dtors` section is occurring in the final linked artifact. It was caused by a few crates using the `.ctors` link section manually, and by using a very (~6 year) old version of the [ctor](https://crates.io/crates/ctor) crate.

[Crater run analysis](https://hackmd.io/tFDifkUcSLGoHPBRIl0z8w?view#ctorsdtors-sections)

**Possible workaround**
It is possible to [detect](https://github.com/rust-lang/rust/commit/e5e2316712e19036eb40e0bf59150f25e35f9880) if `.ctors/.dtors` section is present in the final linked artifact (LLD will keep it there, but it won't be populated), and warn users about it. This check is very cheap and doesn't even appear on [perf](https://github.com/rust-lang/rust/pull/112049#issuecomment-2661125340). We have benchmarked the check on a 240 MiB Chrome binary, where it took 0.8ms with page cache flushed, and 0.06ms with page cache primed (which should be the common case, as the linked artifact is written to disk just before the check is performed).

In theory, this could be also solved with a linker script that moves `.ctors` to `.init_array`.

We think that these sections should be so rare that it is not worth it to implement any workarounds for now.

---

### Different garbage collection behavior
[#130397](https://github.com/rust-lang/rust/issues/130397) reported an issue where LLD prunes a local symbol, so it is missing in the linked artifact. However, BFD keeps the same symbol, so it is a regression. This is caused by a difference in linker garbage collection.

Rust uses `--gc-sections` and puts each function into a separate linker section, which prunes unused code. There is some code (specifically the somewhat popular [linkme](https://github.com/dtolnay/linkme) crate) that (arguably ab-)uses so called linker encapsulation symbols to achieve distributed slices.

BFD (2.37+) uses a conservative linking mode that works as intended with this behavior, but it might slightly increase binary size of the linked artifact. LLD does not use this workaround by default, which causes the sections to be eliminated, but it can be made to use the conservative mode using [`-z nostart-stop-gc`](https://lld.llvm.org/ELF/start-stop-gc.html#z-start-stop-gc).

To avoid this issue, we told LLD to use the [conservative mode](https://github.com/rust-lang/rust/pull/137685), which maintains backwards compatibility with BFD. We found that it has [no effect](https://github.com/rust-lang/rust/pull/112049#issuecomment-2666028775) on compilation performance and binary size in our benchmark suite. With this change, `linkme` works. Since then, rust-lang/rust#140872 removed `linkme` distributed slice's dependence on conservative GC behavior, so this PR also removes that conservative mode: no transition period is necessary, as the PR immediately fixed the crate with no source changes.

[Crater run analysis](https://hackmd.io/tFDifkUcSLGoHPBRIl0z8w?view#Different-garbage-collection-behavior)

---

### Various uncommon issues

A small number of issues that only occurred in a handful of instances were found in crater, and it is unclear if LLD is at fault or if there is some other issue that was not detected with BFD.

You can examine these [here](https://hackmd.io/tFDifkUcSLGoHPBRIl0z8w?view#Various-uncommon-issues).

---

### Missing jobserver support
LLD doesn't support the jobserver protocol for limiting the number of threads used, it simply defaults to using all available cores, and is one of the reasons why it's faster than BFD. However, this should mostly be a non-issue, because most of the linking done during high parallelism sections of `cargo build` is linking of build scripts and proc macros, which are typically very fast to link (e.g. ~50ms), and a potential oversubscription of cores thus doesn't hurt that much.

When the final artifact is linked (which typically takes the most time), there should be no other sources of parallelism conflicts from compiling other code, so LLD should be able to use all available threads.

That being said, it is a difference of behavior, where previously a `-j` flag was generally not using more cpu than the specified limit. It can be impactful in some resource-constrained systems, but to be clear that is already the case today due to [cargo parallelism](https://github.com/rust-lang/cargo/issues/9157). This could be one reason to opt out of using `rust-lld` on some systems.

LLD has support for limiting the number of threads to use, so in theory rustc could try to get all the jobserver tokens available and use that as lld's thread limit. It'd still be suboptimal as new tokens would not be dynamically detected, and we could be using less threads than available.

We did a benchmark on a real-world crate that shows that using multiple LLD threads for intermediate artifacts doesn't seem to have a performance effect. You can find it [here](https://hackmd.io/tFDifkUcSLGoHPBRIl0z8w?view#Missing-jobserver-support).

---

#### Opting out of LLD in the ecosystem
We have also examined repositories where people opted out of LLD on nightly, using [this GitHub query](https://github.com/search?q=%22linker-features%3D-lld%22&type=code). The summary can be found below:

<details>
<summary>Summary of LLD opt outs</summary>

> This examination was performed on 2025-03-09.

Here we briefly examine the most common reasons why people use `-Zlinker-features=-lld`, based on comments and git history.

- Nix/NixOS ([1](https://github.com/rszyma/vscode-kanata/blob/59d703dff5a238b14ab3759cac27f73fb34bbcfe/flake.nix#L33), [2](https://github.com/sbernauer/breakwater/blob/3cc3449fc126c5c99d4a971733fd32be589884e0/.cargo/config.toml#L4), [3](https://github.com/tiiuae/ebpf-firewall/blame/32bdb17cedd1c9bea1ab3482623de458d95da7d0/.cargo/config.toml#L2), [4](https://github.com/jules-sommer/wavetheme-gen/blob/f5f657d014d4a30607625afb70f810c229c0294e/Cargo.toml#L4), [5](https://github.com/LayerTwo-Labs/zside-rust/blob/e4266f5c5571a1b180a9c70cf0939c7070e410c7/.cargo/config.toml#L10), [6](https://github.com/przyjacielpkp/zkml/blob/22a4aef24e9d2c77789229d7c634fc67e9eb1184/README.md?plain=1#L78), [7](https://github.com/LayerTwo-Labs/thunder-rust/blob/2222d53474c8d2d0428b4c56f8157095dced6d5a/.cargo/config.toml#L2), [8](https://github.com/enesoztrk/nixos-tc-aya-test/blob/b2ffa59d3eba8b60fd04b0a4c8bbe047400eb981/.cargo/config.toml#L4), [9](https://github.com/lowRISC/container-hotplug/blob/3ead4ef9c7f79c303392178c99677dbecff1aea6/.cargo/config.toml#L2), [10](https://github.com/Eliah-Lakhin/ad-astra/blob/ca6b8c8a5dba7bb5e894f3f1013f17876962a021/work/examples/lsp-client/src/extension.ts#L94))
    - There was an [issue](https://github.com/NixOS/nixpkgs/issues/312661) with LLD, which seems to have been fixed with https://github.com/NixOS/nixpkgs/pull/314268.
 It's unclear whether that fixed all the Nix issues though.
- Issues with linkme ([1](https://github.com/0xPolygonZero/zk_evm/blob/ef388619ffbd5305209519a3a5bc0396185d68ac/.cargo/config.toml#L4), [2](https://github.com/conjure-cp/conjure-oxide/blob/be0fc5827ff90e8486d416cc184b6ce24f73bf01/README.md?plain=1#L20), [3](https://github.com/clchiou/garage/blob/c5d8444d56bb6ee24ca95e5c6b9880ed996f4918/rust/.cargo/config.toml#L6), [4](https://github.com/PonasKovas/craftflow/blob/5b4cc1a5196e08a975368399fefda4b71f3a2f6f/.cargo/config.toml#L3), [5](https://github.com/kezhuw/zookeeper-client-rust/blob/4e27c7de2a7cc5e709af012b791c8fea9bb47f1f/.github/workflows/ci.yml#L82), [6](https://github.com/niklasdewally/conjure-oxide/blob/8fe60c12bca7011a2f9eded4b7c95ad0e77b6f44/.github/workflows/code-coverage.yml#L48), [7](https://github.com/kezhuw/spawns/blob/c8b468379805de9df3287c01b94b4ed3db6b61ed/.github/workflows/ci.yml#L74))
    - These should be resolved with the conservative garbage collection ([#137685](https://github.com/rust-lang/rust/pull/137685)).
- Bazel ([1](https://github.com/google-parfait/confidential-federated-compute/blob/1823f69ed8f5f4f819f7bfa21da1ca629fdc826b/.bazelrc#L71)), WASM ([1](https://github.com/Eliah-Lakhin/ad-astra/blob/ca6b8c8a5dba7bb5e894f3f1013f17876962a021/work/examples/wasm-build.sh#L37), [2](https://github.com/yacineb/pgrx-wasi-test/blob/2bf99037ca1b650b2cbc35f1257a87fb6ead0920/build.sh#L21)), uncategorized ([2](https://github.com/nbdd0121/r2vm/blob/5118be6b9e757c6fef2f019385873f403c23c548/.cargo/config.toml#L3), [3](https://github.com/Wyvern/Img/blame/45020c7e1dc4926c8129647014c708db0c13f463/.cargo/config.toml#L209), [4](https://github.com/arnaudpoullet/leptos-i18n-compile-error/blob/042eb835f7ca0dc36be67cf7fe65b35b22b6059f/README.md?plain=1#L89), [5](https://github.com/JonLeeCon/numerical-rust-cpu/blob/fd0b3006768ed81c56147044dc05c92b11b7b6f0/exercises/.cargo/config.toml#L13), [6](https://github.com/PonasKovas/shallowclone/blob/be65f2ec923cac6ceedbc8db520c89969ebfce7c/.github/workflows/rust.yml#L20))
    - Reason unclear.
</details>

## History
The idea to use a faster linker by default has been on the radar for quite some time ([#39915](https://github.com/rust-lang/rust/issues/39915), [#71515](https://github.com/rust-lang/rust/issues/71515)). There were [very early attempts](https://github.com/rust-lang/rust/pull/29974) to use the gold linker by default, but these had to be [reverted](https://github.com/rust-lang/rust/pull/30913) because of compatibility issues. Support for LLD was implemented back in [2017](https://github.com/rust-lang/rust/pull/40018), but it has not been made default yet, except for some more niche targets, such as [WASM](https://github.com/rust-lang/rust/pull/48125), [ARM Cortex](https://github.com/rust-lang/rust/pull/53648) or [RISC-V](https://github.com/rust-lang/rust/pull/53822).

It took quite some time to figure out how should the interface for selecting the linker (and the way it is invoked) look like, as it differs a lot between different platforms, linkers and compiler drivers. During that time, LLD has matured and achieved [almost perfect compatibility](https://maskray.me/blog/2020-12-19-lld-and-gnu-linker-incompatibilities) with the default Linux linker (BFD).

- [#56351](https://github.com/rust-lang/rust/pull/56351) stabilized `-Clinker-flavor`, which is used to determine how to invoke the linker. It is especially useful on targets where selecting the linker directly with `-Clinker` is not possible or is impractical.
    - December 2018, author `@davidtwco,` reviewer `@nagisa`
- [#76158](https://github.com/rust-lang/rust/pull/76158) stabilized `-Clink-self-contained=[y|n]`, which allows overriding the compiler's heuristic for deciding whether it should use self-contained or external tools (linker, sanitizers, libc, etc.). It only allowed using the self-contained mode either for everything (`y`) or nothing (`n`), but did not allow granular choice.
    - September 2020, author `@mati864,` reviewer `@petrochenkov`
- [#85961](https://github.com/rust-lang/rust/pull/85961) implemented the `-Zgcc-ld` flag, which was a hacky way of opting into LLD usage.
    - June 2021, author `@sledgehammervampire,` reviewer `@petrochenkov`
- [MCP 510](https://github.com/rust-lang/compiler-team/issues/510) proposed stabilizing the behavior of `-Zgcc-ld` using more granular flags (`-Clink-self-contained=linker -Clinker-flavor=gcc-lld`).
    - Initially implemented in [#96827](https://github.com/rust-lang/rust/pull/96827), but `@petrochenkov` [suggested](https://github.com/rust-lang/rust/pull/96827#issuecomment-1208441595) a slightly different approach.
    - The PR was split into [#96884](https://github.com/rust-lang/rust/pull/96884), where it was decided what will be the individual components of `-Clink-self-contained=linker`.
    - And [#96401](https://github.com/rust-lang/rust/pull/96401), which implemented the `-Clinker-flavor` part.
    - The MCP was finally implemented in [#112910](https://github.com/rust-lang/rust/pull/112910).
    - [#116514](https://github.com/rust-lang/rust/pull/116514) then removed `-Zgcc-ld`, as it was replaced by `-Clinker-flavor=gnu-lld-cc` + `-Clink-self-contained=linker`.
    - April 2022 - October 2023, author `@lqd,` reviewer `@petrochenkov`

- Various linker handling refactorings were performed in the meantime: [#97375](https://github.com/rust-lang/rust/pull/97375), [#98212](https://github.com/rust-lang/rust/pull/98212), [#100126](https://github.com/rust-lang/rust/pull/100126), [#100552](https://github.com/rust-lang/rust/pull/100552), [#102836](https://github.com/rust-lang/rust/pull/102836), [#110807](https://github.com/rust-lang/rust/pull/110807), [#101988](https://github.com/rust-lang/rust/pull/101988), [#116515](https://github.com/rust-lang/rust/pull/116515)

- The implementation of linker flavors with LLD was causing a sort of a combinatorial explosion of various options.
[#119906](https://github.com/rust-lang/rust/pull/119906) suggested a different approach for linker flavors (described [here](https://github.com/rust-lang/rust/pull/119906#issuecomment-1894088306)), where the individual flavors could be enabled separately using `+/-` (e.g. `+lld`).
    - After some back and forth, this idea was moved to `-Clinker-features` (see [comment 1](https://github.com/rust-lang/rust/pull/119906#issuecomment-1895693162) and [comment 2](https://github.com/rust-lang/rust/pull/119906#issuecomment-1980801438)), which was implemented in [#123656](https://github.com/rust-lang/rust/pull/123656).
    - April 2024, author `@lqd,` reviewer `@petrochenkov`
- [#124129](https://github.com/rust-lang/rust/pull/124129) enabled LLD by default on nightly.
    - April 2024, author `@lqd,` reviewer `@petrochenkov`
- [#137685](https://github.com/rust-lang/rust/pull/137685), [#137926](https://github.com/rust-lang/rust/pull/137926) enabled the conservative gargage collection mode (`-znostart-stop-gc`) to improve compatibility with BFD.
    - February 2025, author `@lqd,` reviewer `@petrochenkov` (implementation), author `@kobzol,` reviewer `@lqd` (test)
- [#96025](https://github.com/rust-lang/rust/pull/96025) (April 2022), [#117684](https://github.com/rust-lang/rust/pull/117684) (November 2023), [#137044](https://github.com/rust-lang/rust/pull/137044) (February 2025): crater runs.

## Unresolved questions/concerns
- Is changing the linker considered a breaking change? In (hopefully very rare) cases, it might break some existing code. It should mostly only affect the final linked artifact, so it should be easy to opt out.
- Similarly, is the single-threaded behavior of such tools encompassed in our stability guarantee: it can be observed via the `-j` job limit (though I believe we have/had some open issues on sometimes using more CPU resources than the job count limit implied). As mentioned above, LLD does not support the jobserver protocol.
- A concern [was raised](https://github.com/rust-lang/rust/issues/71515#issuecomment-2612370229) about increased memory usage of LLD. We should probably let users know about the possibly increased memory usage, and jobserver incompatibility: we did so when announcing this landing on nightly.
- LLD seems to produce [slightly larger](https://perf.rust-lang.org/compare.html?start=b3e117044c7f707293edc040edb93e7ec5f7040a&end=baed03c51a68376c1789cc373581eea0daf89967&stat=size%3Alinked_artifact&tab=compile) binary artifacts. This can be partially clawed back using Identical Code Folding (`-Clink-args=-Wl,--icf=all`).
- Should we detect the outdated `.ctors/.dtors` sections to provide a better error message, even if that should be rare in practice?

---

### Next steps

After the FCP completes:
- we should land this PR at the beginning of a beta cycle, to maximize time for testing
- keep an eye on the beta crater run results for possible linker issues (or do a dedicated beta crater run with only this change)
- release a blog post announcing the change, and asking for testing feedback of the appropriate beta
- depending on feedback, or if a period of testing of 6 weeks is not long enough, we could keep this change on beta for another cycle

---

Development, testing, try builds were done in https://github.com/rust-lang/rust/pull/138645.

r? `@petrochenkov`
`@rustbot` label +needs-fcp +T-compiler

48 files changed, 353 insertions, 176 deletions

diff --git a/compiler/rustc_codegen_ssa/src/back/link.rs b/compiler/rustc_codegen_ssa/src/back/link.rs
index 343cb0eeca9..b46773396fc 100644
--- a/compiler/rustc_codegen_ssa/src/back/link.rs
+++ b/compiler/rustc_codegen_ssa/src/back/link.rs
@@ -1379,7 +1379,7 @@ pub fn linker_and_flavor(sess: &Session) -> (PathBuf, LinkerFlavor) {
         }
     }
 
-    let features = sess.opts.unstable_opts.linker_features;
+    let features = sess.opts.cg.linker_features;
 
     // linker and linker flavor specified via command line have precedence over what the target
     // specification specifies
@@ -3327,35 +3327,6 @@ fn add_lld_args(
     // this, `wasm-component-ld`, which is overridden if this option is passed.
     if !sess.target.is_like_wasm {
         cmd.cc_arg("-fuse-ld=lld");
-
-        // On ELF platforms like at least x64 linux, GNU ld and LLD have opposite defaults on some
-        // section garbage-collection features. For example, the somewhat popular `linkme` crate and
-        // its dependents rely in practice on this difference: when using lld, they need `-z
-        // nostart-stop-gc` to prevent encapsulation symbols and sections from being
-        // garbage-collected.
-        //
-        // More information about all this can be found in:
-        // - https://maskray.me/blog/2021-01-31-metadata-sections-comdat-and-shf-link-order
-        // - https://lld.llvm.org/ELF/start-stop-gc
-        //
-        // So when using lld, we restore, for now, the traditional behavior to help migration, but
-        // will remove it in the future.
-        // Since this only disables an optimization, it shouldn't create issues, but is in theory
-        // slightly suboptimal. However, it:
-        // - doesn't have any visible impact on our benchmarks
-        // - reduces the need to disable lld for the crates that depend on this
-        //
-        // Note that lld can detect some cases where this difference is relied on, and emits a
-        // dedicated error to add this link arg. We could make use of this error to emit an FCW. As
-        // of writing this, we don't do it, because lld is already enabled by default on nightly
-        // without this mitigation: no working project would see the FCW, so we do this to help
-        // stabilization.
-        //
-        // FIXME: emit an FCW if linking fails due its absence, and then remove this link-arg in the
-        // future.
-        if sess.target.llvm_target == "x86_64-unknown-linux-gnu" {
-            cmd.link_arg("-znostart-stop-gc");
-        }
     }
 
     if !flavor.is_gnu() {
diff --git a/compiler/rustc_session/src/config.rs b/compiler/rustc_session/src/config.rs
index 4627c2978fc..a91e2140fd4 100644
--- a/compiler/rustc_session/src/config.rs
+++ b/compiler/rustc_session/src/config.rs
@@ -370,12 +370,34 @@ impl LinkSelfContained {
     }
 
     /// To help checking CLI usage while some of the values are unstable: returns whether one of the
-    /// components was set individually. This would also require the `-Zunstable-options` flag, to
-    /// be allowed.
-    fn are_unstable_variants_set(&self) -> bool {
-        let any_component_set =
-            !self.enabled_components.is_empty() || !self.disabled_components.is_empty();
-        self.explicitly_set.is_none() && any_component_set
+    /// unstable components was set individually, for the given `TargetTuple`. This would also
+    /// require the `-Zunstable-options` flag, to be allowed.
+    fn check_unstable_variants(&self, target_tuple: &TargetTuple) -> Result<(), String> {
+        if self.explicitly_set.is_some() {
+            return Ok(());
+        }
+
+        // `-C link-self-contained=-linker` is only stable on x64 linux.
+        let has_minus_linker = self.disabled_components.is_linker_enabled();
+        if has_minus_linker && target_tuple.tuple() != "x86_64-unknown-linux-gnu" {
+            return Err(format!(
+                "`-C link-self-contained=-linker` is unstable on the `{target_tuple}` \
+                    target. The `-Z unstable-options` flag must also be passed to use it on this target",
+            ));
+        }
+
+        // Any `+linker` or other component used is unstable, and that's an error.
+        let unstable_enabled = self.enabled_components;
+        let unstable_disabled = self.disabled_components - LinkSelfContainedComponents::LINKER;
+        if !unstable_enabled.union(unstable_disabled).is_empty() {
+            return Err(String::from(
+                "only `-C link-self-contained` values `y`/`yes`/`on`/`n`/`no`/`off`/`-linker` \
+                are stable, the `-Z unstable-options` flag must also be passed to use \
+                the unstable values",
+            ));
+        }
+
+        Ok(())
     }
 
     /// Returns whether the self-contained linker component was enabled on the CLI, using the
@@ -402,7 +424,7 @@ impl LinkSelfContained {
     }
 }
 
-/// The different values that `-Z linker-features` can take on the CLI: a list of individually
+/// The different values that `-C linker-features` can take on the CLI: a list of individually
 /// enabled or disabled features used during linking.
 ///
 /// There is no need to enable or disable them in bulk. Each feature is fine-grained, and can be
@@ -442,6 +464,39 @@ impl LinkerFeaturesCli {
             _ => None,
         }
     }
+
+    /// When *not* using `-Z unstable-options` on the CLI, ensure only stable linker features are
+    /// used, for the given `TargetTuple`. Returns `Ok` if no unstable variants are used.
+    /// The caller should ensure that e.g. `nightly_options::is_unstable_enabled()`
+    /// returns false.
+    pub(crate) fn check_unstable_variants(&self, target_tuple: &TargetTuple) -> Result<(), String> {
+        // `-C linker-features=-lld` is only stable on x64 linux.
+        let has_minus_lld = self.disabled.is_lld_enabled();
+        if has_minus_lld && target_tuple.tuple() != "x86_64-unknown-linux-gnu" {
+            return Err(format!(
+                "`-C linker-features=-lld` is unstable on the `{target_tuple}` \
+                    target. The `-Z unstable-options` flag must also be passed to use it on this target",
+            ));
+        }
+
+        // Any `+lld` or non-lld feature used is unstable, and that's an error.
+        let unstable_enabled = self.enabled;
+        let unstable_disabled = self.disabled - LinkerFeatures::LLD;
+        if !unstable_enabled.union(unstable_disabled).is_empty() {
+            let unstable_features: Vec<_> = unstable_enabled
+                .iter()
+                .map(|f| format!("+{}", f.as_str().unwrap()))
+                .chain(unstable_disabled.iter().map(|f| format!("-{}", f.as_str().unwrap())))
+                .collect();
+            return Err(format!(
+                "`-C linker-features={}` is unstable, and also requires the \
+                `-Z unstable-options` flag to be used",
+                unstable_features.join(","),
+            ));
+        }
+
+        Ok(())
+    }
 }
 
 /// Used with `-Z assert-incr-state`.
@@ -2638,26 +2693,21 @@ pub fn build_session_options(early_dcx: &mut EarlyDiagCtxt, matches: &getopts::M
         }
     }
 
-    if !nightly_options::is_unstable_enabled(matches)
-        && cg.force_frame_pointers == FramePointer::NonLeaf
-    {
+    let unstable_options_enabled = nightly_options::is_unstable_enabled(matches);
+    if !unstable_options_enabled && cg.force_frame_pointers == FramePointer::NonLeaf {
         early_dcx.early_fatal(
             "`-Cforce-frame-pointers=non-leaf` or `always` also requires `-Zunstable-options` \
                 and a nightly compiler",
         )
     }
 
-    // For testing purposes, until we have more feedback about these options: ensure `-Z
-    // unstable-options` is required when using the unstable `-C link-self-contained` and `-C
-    // linker-flavor` options.
-    if !nightly_options::is_unstable_enabled(matches) {
-        let uses_unstable_self_contained_option =
-            cg.link_self_contained.are_unstable_variants_set();
-        if uses_unstable_self_contained_option {
-            early_dcx.early_fatal(
-                "only `-C link-self-contained` values `y`/`yes`/`on`/`n`/`no`/`off` are stable, \
-                the `-Z unstable-options` flag must also be passed to use the unstable values",
-            );
+    let target_triple = parse_target_triple(early_dcx, matches);
+
+    // Ensure `-Z unstable-options` is required when using the unstable `-C link-self-contained` and
+    // `-C linker-flavor` options.
+    if !unstable_options_enabled {
+        if let Err(error) = cg.link_self_contained.check_unstable_variants(&target_triple) {
+            early_dcx.early_fatal(error);
         }
 
         if let Some(flavor) = cg.linker_flavor {
@@ -2697,7 +2747,6 @@ pub fn build_session_options(early_dcx: &mut EarlyDiagCtxt, matches: &getopts::M
 
     let cg = cg;
 
-    let target_triple = parse_target_triple(early_dcx, matches);
     let opt_level = parse_opt_level(early_dcx, matches, &cg);
     // The `-g` and `-C debuginfo` flags specify the same setting, so we want to be able
     // to use them interchangeably. See the note above (regarding `-O` and `-C opt-level`)
@@ -2706,6 +2755,12 @@ pub fn build_session_options(early_dcx: &mut EarlyDiagCtxt, matches: &getopts::M
     let debuginfo = select_debuginfo(matches, &cg);
     let debuginfo_compression = unstable_opts.debuginfo_compression;
 
+    if !unstable_options_enabled {
+        if let Err(error) = cg.linker_features.check_unstable_variants(&target_triple) {
+            early_dcx.early_fatal(error);
+        }
+    }
+
     let crate_name = matches.opt_str("crate-name");
     let unstable_features = UnstableFeatures::from_environment(crate_name.as_deref());
     // Parse any `-l` flags, which link to native libraries.
diff --git a/compiler/rustc_session/src/options.rs b/compiler/rustc_session/src/options.rs
index ecd82c0cc01..626262c8442 100644
--- a/compiler/rustc_session/src/options.rs
+++ b/compiler/rustc_session/src/options.rs
@@ -2015,6 +2015,8 @@ options! {
         on a C toolchain or linker installed in the system"),
     linker: Option<PathBuf> = (None, parse_opt_pathbuf, [UNTRACKED],
         "system linker to link outputs with"),
+    linker_features: LinkerFeaturesCli = (LinkerFeaturesCli::default(), parse_linker_features, [UNTRACKED],
+        "a comma-separated list of linker features to enable (+) or disable (-): `lld`"),
     linker_flavor: Option<LinkerFlavorCli> = (None, parse_linker_flavor, [UNTRACKED],
         "linker flavor"),
     linker_plugin_lto: LinkerPluginLto = (LinkerPluginLto::Disabled,
@@ -2307,8 +2309,6 @@ options! {
         "link native libraries in the linker invocation (default: yes)"),
     link_only: bool = (false, parse_bool, [TRACKED],
         "link the `.rlink` file generated by `-Z no-link` (default: no)"),
-    linker_features: LinkerFeaturesCli = (LinkerFeaturesCli::default(), parse_linker_features, [UNTRACKED],
-        "a comma-separated list of linker features to enable (+) or disable (-): `lld`"),
     lint_llvm_ir: bool = (false, parse_bool, [TRACKED],
         "lint LLVM IR (default: no)"),
     lint_mir: bool = (false, parse_bool, [UNTRACKED],
diff --git a/compiler/rustc_target/src/spec/mod.rs b/compiler/rustc_target/src/spec/mod.rs
index 5346b206a17..4bc0d88a910 100644
--- a/compiler/rustc_target/src/spec/mod.rs
+++ b/compiler/rustc_target/src/spec/mod.rs
@@ -725,7 +725,7 @@ impl ToJson for LinkSelfContainedComponents {
 }
 
 bitflags::bitflags! {
-    /// The `-Z linker-features` components that can individually be enabled or disabled.
+    /// The `-C linker-features` components that can individually be enabled or disabled.
     ///
     /// They are feature flags intended to be a more flexible mechanism than linker flavors, and
     /// also to prevent a combinatorial explosion of flavors whenever a new linker feature is
@@ -756,7 +756,7 @@ bitflags::bitflags! {
 rustc_data_structures::external_bitflags_debug! { LinkerFeatures }
 
 impl LinkerFeatures {
-    /// Parses a single `-Z linker-features` well-known feature, not a set of flags.
+    /// Parses a single `-C linker-features` well-known feature, not a set of flags.
     pub fn from_str(s: &str) -> Option<LinkerFeatures> {
         Some(match s {
             "cc" => LinkerFeatures::CC,
@@ -765,6 +765,17 @@ impl LinkerFeatures {
         })
     }
 
+    /// Return the linker feature name, as would be passed on the CLI.
+    ///
+    /// Returns `None` if the bitflags aren't a singular component (but a mix of multiple flags).
+    pub fn as_str(self) -> Option<&'static str> {
+        Some(match self {
+            LinkerFeatures::CC => "cc",
+            LinkerFeatures::LLD => "lld",
+            _ => return None,
+        })
+    }
+
     /// Returns whether the `lld` linker feature is enabled.
     pub fn is_lld_enabled(self) -> bool {
         self.contains(LinkerFeatures::LLD)
diff --git a/src/bootstrap/src/core/build_steps/compile.rs b/src/bootstrap/src/core/build_steps/compile.rs
index 3e2bdc2d6b5..ca74771bb6e 100644
--- a/src/bootstrap/src/core/build_steps/compile.rs
+++ b/src/bootstrap/src/core/build_steps/compile.rs
@@ -1369,9 +1369,7 @@ pub fn rustc_cargo_env(
     }
 
     // Enable rustc's env var for `rust-lld` when requested.
-    if builder.config.lld_enabled
-        && (builder.config.channel == "dev" || builder.config.channel == "nightly")
-    {
+    if builder.config.lld_enabled {
         cargo.env("CFG_USE_SELF_CONTAINED_LINKER", "1");
     }
 
diff --git a/src/bootstrap/src/core/build_steps/test.rs b/src/bootstrap/src/core/build_steps/test.rs
index a5b7b22aba8..716bef3f38c 100644
--- a/src/bootstrap/src/core/build_steps/test.rs
+++ b/src/bootstrap/src/core/build_steps/test.rs
@@ -262,7 +262,13 @@ impl Step for Cargotest {
             .args(builder.config.test_args())
             .env("RUSTC", builder.rustc(compiler))
             .env("RUSTDOC", builder.rustdoc(compiler));
-        add_rustdoc_cargo_linker_args(&mut cmd, builder, compiler.host, LldThreads::No);
+        add_rustdoc_cargo_linker_args(
+            &mut cmd,
+            builder,
+            compiler.host,
+            LldThreads::No,
+            compiler.stage,
+        );
         cmd.delay_failure().run(builder);
     }
 }
@@ -857,7 +863,7 @@ impl Step for RustdocTheme {
             .env("CFG_RELEASE_CHANNEL", &builder.config.channel)
             .env("RUSTDOC_REAL", builder.rustdoc(self.compiler))
             .env("RUSTC_BOOTSTRAP", "1");
-        cmd.args(linker_args(builder, self.compiler.host, LldThreads::No));
+        cmd.args(linker_args(builder, self.compiler.host, LldThreads::No, self.compiler.stage));
 
         cmd.delay_failure().run(builder);
     }
@@ -1033,7 +1039,13 @@ impl Step for RustdocGUI {
         cmd.env("RUSTDOC", builder.rustdoc(self.compiler))
             .env("RUSTC", builder.rustc(self.compiler));
 
-        add_rustdoc_cargo_linker_args(&mut cmd, builder, self.compiler.host, LldThreads::No);
+        add_rustdoc_cargo_linker_args(
+            &mut cmd,
+            builder,
+            self.compiler.host,
+            LldThreads::No,
+            self.compiler.stage,
+        );
 
         for path in &builder.paths {
             if let Some(p) = helpers::is_valid_test_suite_arg(path, "tests/rustdoc-gui", builder) {
@@ -1812,7 +1824,7 @@ NOTE: if you're sure you want to do this, please open an issue as to why. In the
         }
 
         let mut hostflags = flags.clone();
-        hostflags.extend(linker_flags(builder, compiler.host, LldThreads::No));
+        hostflags.extend(linker_flags(builder, compiler.host, LldThreads::No, compiler.stage));
 
         let mut targetflags = flags;
 
diff --git a/src/bootstrap/src/core/builder/cargo.rs b/src/bootstrap/src/core/builder/cargo.rs
index deb7106f185..065d7e45e0f 100644
--- a/src/bootstrap/src/core/builder/cargo.rs
+++ b/src/bootstrap/src/core/builder/cargo.rs
@@ -115,7 +115,7 @@ impl Cargo {
             // No need to configure the target linker for these command types.
             Kind::Clean | Kind::Check | Kind::Suggest | Kind::Format | Kind::Setup => {}
             _ => {
-                cargo.configure_linker(builder);
+                cargo.configure_linker(builder, mode);
             }
         }
 
@@ -209,7 +209,7 @@ impl Cargo {
 
     // FIXME(onur-ozkan): Add coverage to make sure modifications to this function
     // doesn't cause cache invalidations (e.g., #130108).
-    fn configure_linker(&mut self, builder: &Builder<'_>) -> &mut Cargo {
+    fn configure_linker(&mut self, builder: &Builder<'_>, mode: Mode) -> &mut Cargo {
         let target = self.target;
         let compiler = self.compiler;
 
@@ -264,7 +264,12 @@ impl Cargo {
             }
         }
 
-        for arg in linker_args(builder, compiler.host, LldThreads::Yes) {
+        // We use the snapshot compiler when building host code (build scripts/proc macros) of
+        // `Mode::Std` tools, so we need to determine the current stage here to pass the proper
+        // linker args (e.g. -C vs -Z).
+        // This should stay synchronized with the [cargo] function.
+        let host_stage = if mode == Mode::Std { 0 } else { compiler.stage };
+        for arg in linker_args(builder, compiler.host, LldThreads::Yes, host_stage) {
             self.hostflags.arg(&arg);
         }
 
@@ -274,10 +279,10 @@ impl Cargo {
         }
         // We want to set -Clinker using Cargo, therefore we only call `linker_flags` and not
         // `linker_args` here.
-        for flag in linker_flags(builder, target, LldThreads::Yes) {
+        for flag in linker_flags(builder, target, LldThreads::Yes, compiler.stage) {
             self.rustflags.arg(&flag);
         }
-        for arg in linker_args(builder, target, LldThreads::Yes) {
+        for arg in linker_args(builder, target, LldThreads::Yes, compiler.stage) {
             self.rustdocflags.arg(&arg);
         }
 
diff --git a/src/bootstrap/src/core/builder/mod.rs b/src/bootstrap/src/core/builder/mod.rs
index b96a988cde3..7464327fde9 100644
--- a/src/bootstrap/src/core/builder/mod.rs
+++ b/src/bootstrap/src/core/builder/mod.rs
@@ -1599,7 +1599,7 @@ You have to build a stage1 compiler for `{}` first, and then use it to build a s
             cmd.arg("-Dwarnings");
         }
         cmd.arg("-Znormalize-docs");
-        cmd.args(linker_args(self, compiler.host, LldThreads::Yes));
+        cmd.args(linker_args(self, compiler.host, LldThreads::Yes, compiler.stage));
         cmd
     }
 
diff --git a/src/bootstrap/src/core/config/toml/rust.rs b/src/bootstrap/src/core/config/toml/rust.rs
index ac5eaea3bcb..0fae235bb93 100644
--- a/src/bootstrap/src/core/config/toml/rust.rs
+++ b/src/bootstrap/src/core/config/toml/rust.rs
@@ -619,7 +619,6 @@ impl Config {
         // build our internal lld and use it as the default linker, by setting the `rust.lld` config
         // to true by default:
         // - on the `x86_64-unknown-linux-gnu` target
-        // - on the `dev` and `nightly` channels
         // - when building our in-tree llvm (i.e. the target has not set an `llvm-config`), so that
         //   we're also able to build the corresponding lld
         // - or when using an external llvm that's downloaded from CI, which also contains our prebuilt
@@ -628,9 +627,7 @@ impl Config {
         //   thus, disabled
         // - similarly, lld will not be built nor used by default when explicitly asked not to, e.g.
         //   when the config sets `rust.lld = false`
-        if self.host_target.triple == "x86_64-unknown-linux-gnu"
-            && self.hosts == [self.host_target]
-            && (self.channel == "dev" || self.channel == "nightly")
+        if self.host_target.triple == "x86_64-unknown-linux-gnu" && self.hosts == [self.host_target]
         {
             let no_llvm_config = self
                 .target_config
diff --git a/src/bootstrap/src/utils/helpers.rs b/src/bootstrap/src/utils/helpers.rs
index 3c5f612daa7..eb00ed566c2 100644
--- a/src/bootstrap/src/utils/helpers.rs
+++ b/src/bootstrap/src/utils/helpers.rs
@@ -404,8 +404,9 @@ pub fn linker_args(
     builder: &Builder<'_>,
     target: TargetSelection,
     lld_threads: LldThreads,
+    stage: u32,
 ) -> Vec<String> {
-    let mut args = linker_flags(builder, target, lld_threads);
+    let mut args = linker_flags(builder, target, lld_threads, stage);
 
     if let Some(linker) = builder.linker(target) {
         args.push(format!("-Clinker={}", linker.display()));
@@ -420,19 +421,30 @@ pub fn linker_flags(
     builder: &Builder<'_>,
     target: TargetSelection,
     lld_threads: LldThreads,
+    stage: u32,
 ) -> Vec<String> {
     let mut args = vec![];
     if !builder.is_lld_direct_linker(target) && builder.config.lld_mode.is_used() {
         match builder.config.lld_mode {
             LldMode::External => {
-                args.push("-Zlinker-features=+lld".to_string());
-                // FIXME(kobzol): remove this flag once MCP510 gets stabilized
+                // cfg(bootstrap) - remove the stage 0 check after updating the bootstrap compiler:
+                // `-Clinker-features` has been stabilized.
+                if stage == 0 {
+                    args.push("-Zlinker-features=+lld".to_string());
+                } else {
+                    args.push("-Clinker-features=+lld".to_string());
+                }
                 args.push("-Zunstable-options".to_string());
             }
             LldMode::SelfContained => {
-                args.push("-Zlinker-features=+lld".to_string());
+                // cfg(bootstrap) - remove the stage 0 check after updating the bootstrap compiler:
+                // `-Clinker-features` has been stabilized.
+                if stage == 0 {
+                    args.push("-Zlinker-features=+lld".to_string());
+                } else {
+                    args.push("-Clinker-features=+lld".to_string());
+                }
                 args.push("-Clink-self-contained=+linker".to_string());
-                // FIXME(kobzol): remove this flag once MCP510 gets stabilized
                 args.push("-Zunstable-options".to_string());
             }
             LldMode::Unused => unreachable!(),
@@ -453,8 +465,9 @@ pub fn add_rustdoc_cargo_linker_args(
     builder: &Builder<'_>,
     target: TargetSelection,
     lld_threads: LldThreads,
+    stage: u32,
 ) {
-    let args = linker_args(builder, target, lld_threads);
+    let args = linker_args(builder, target, lld_threads, stage);
     let mut flags = cmd
         .get_envs()
         .find_map(|(k, v)| if k == OsStr::new("RUSTDOCFLAGS") { v } else { None })
diff --git a/src/doc/rustc/src/codegen-options/index.md b/src/doc/rustc/src/codegen-options/index.md
index bb109adf76f..07eafdf4c4c 100644
--- a/src/doc/rustc/src/codegen-options/index.md
+++ b/src/doc/rustc/src/codegen-options/index.md
@@ -235,15 +235,33 @@ coverage measurement. Its use is not recommended.
 
 ## 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 of those in the system.
-It takes one of the following values:
+This flag controls whether the linker will use libraries and objects shipped with Rust instead of
+those in the system.  It also controls which binary is used for the linker itself. This allows
+overriding cases when detection fails or the user wants to use shipped libraries.
+
+You can enable or disable the usage of any self-contained components using one of the following values:
 
 * no value: rustc will use heuristic to disable self-contained mode if system has necessary tools.
 * `y`, `yes`, `on`, `true`: use only libraries/objects shipped with Rust.
 * `n`, `no`, `off` or `false`: rely on the user or the linker to provide non-Rust libraries/objects.
 
-This allows overriding cases when detection fails or user wants to use shipped libraries.
+It is also possible to enable or disable specific self-contained components in a more granular way.
+You can pass a comma-separated list of self-contained components, individually enabled
+(`+component`) or disabled (`-component`).
+
+Currently, only the `linker` granular option is stabilized, and only on the `x86_64-unknown-linux-gnu` target:
+- `linker`: toggle the usage of self-contained linker binaries (linker, dlltool, and their necessary libraries)
+
+Note that only the `-linker` opt-out is stable on the `x86_64-unknown-linux-gnu` target: `+linker` is
+already the default on this target.
+
+#### Implementation notes
+
+On the `x86_64-unknown-linux-gnu` target, when using the default linker flavor (using `cc` as the
+linker driver) and linker features (to try using `lld`), `rustc` will try to use the self-contained
+linker by passing a `-B /path/to/sysroot/` link argument to the driver to find `rust-lld` in the
+sysroot. For backwards-compatibility, and to limit name and `PATH` collisions, this is done using a
+shim executable (the `lld-wrapper` tool) that forwards execution to the `rust-lld` executable itself.
 
 ## linker
 
@@ -256,6 +274,39 @@ Note that on Unix-like targets (for example, `*-unknown-linux-gnu` or `*-unknown
 the C compiler (for example `cc` or `clang`) is used as the "linker" here, serving as a linker driver.
 It will invoke the actual linker with all the necessary flags to be able to link against the system libraries like libc.
 
+## linker-features
+
+The `-Clinker-features` flag allows enabling or disabling specific features used during linking.
+
+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.
+
+The flag accepts a comma-separated list of features, individually enabled (`+feature`) or disabled
+(`-feature`).
+
+Currently only one is stable, and only on the `x86_64-unknown-linux-gnu` target:
+- `lld`: to toggle trying to use the lld linker, either the system-installed binary, or the self-contained
+  `rust-lld` linker (via the [`-Clink-self-contained=+linker`](#link-self-contained) flag).
+
+For example, use:
+- `-Clinker-features=+lld` to opt into using the `lld` linker, when possible (see the Implementation notes below)
+- `-Clinker-features=-lld` to opt out instead, for targets where it is configured as the default linker
+
+Note that only the `-lld` opt-out is stable on the `x86_64-unknown-linux-gnu` target: `+lld` is
+already the default on this target.
+
+#### Implementation notes
+
+On the `x86_64-unknown-linux-gnu` target, when using the default linker flavor (using `cc` as the
+linker driver), `rustc` will try to use lld by passing a `-fuse-ld=lld` link argument to the driver.
+`rustc` will also try to detect if that _causes_ an error during linking (for example, if GCC is too
+old to understand the flag, and returns an error) and will then retry linking without this argument,
+as a fallback.
+
+If the user _also_ passes a `-Clink-arg=-fuse-ld=$value`, both will be given to the linker
+driver but the user's will be passed last, and would generally have priority over `rustc`'s.
+
 ## linker-flavor
 
 This flag controls the linker flavor used by `rustc`. If a linker is given with
diff --git a/src/doc/unstable-book/src/compiler-flags/codegen-options.md b/src/doc/unstable-book/src/compiler-flags/codegen-options.md
index cc51554706d..f927e5c439c 100644
--- a/src/doc/unstable-book/src/compiler-flags/codegen-options.md
+++ b/src/doc/unstable-book/src/compiler-flags/codegen-options.md
@@ -51,10 +51,10 @@ instead of those in the system. The stable boolean values for this flag are coar
 - `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).
+(beyond parsing the CLI options) and stabilized.
 
 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.
+for the wasm targets). One can also opt into using it by combining this flag with the appropriate
+linker feature: for example, `-Clinker-features=+lld -Clink-self-contained=+linker` will use the
+toolchain's `rust-lld` as the linker instead of the system's lld with `-Clinker-features=+lld` only.
diff --git a/src/doc/unstable-book/src/compiler-flags/linker-features.md b/src/doc/unstable-book/src/compiler-flags/linker-features.md
deleted file mode 100644
index 643fcf7c6d7..00000000000
--- a/src/doc/unstable-book/src/compiler-flags/linker-features.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# `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.
diff --git a/src/tools/opt-dist/src/tests.rs b/src/tools/opt-dist/src/tests.rs
index 705a1750ae8..2d2aab86eda 100644
--- a/src/tools/opt-dist/src/tests.rs
+++ b/src/tools/opt-dist/src/tests.rs
@@ -106,7 +106,10 @@ llvm-config = "{llvm_config}"
             "tests/incremental",
             "tests/mir-opt",
             "tests/pretty",
+            // Make sure that we don't use too new GLIBC symbols on x64
             "tests/run-make/glibc-symbols-x86_64-unknown-linux-gnu",
+            // Make sure that we use LLD by default on x64
+            "tests/run-make/rust-lld-x86_64-unknown-linux-gnu-dist",
             "tests/ui",
             "tests/crashes",
         ];
diff --git a/tests/run-make/compressed-debuginfo-zstd/rmake.rs b/tests/run-make/compressed-debuginfo-zstd/rmake.rs
index cd8cf223047..8d7e5c089da 100644
--- a/tests/run-make/compressed-debuginfo-zstd/rmake.rs
+++ b/tests/run-make/compressed-debuginfo-zstd/rmake.rs
@@ -26,7 +26,7 @@ fn prepare_and_check<F: FnOnce(&mut Rustc) -> &mut Rustc>(to_find: &str, prepare
     run_in_tmpdir(|| {
         let mut rustc = Rustc::new();
         rustc
-            .arg("-Zlinker-features=+lld")
+            .arg("-Clinker-features=+lld")
             .arg("-Clink-self-contained=+linker")
             .arg("-Zunstable-options")
             .arg("-Cdebuginfo=full")
diff --git a/tests/run-make/rust-lld-by-default-beta-stable/main.rs b/tests/run-make/rust-lld-by-default-beta-stable/main.rs
deleted file mode 100644
index f328e4d9d04..00000000000
--- a/tests/run-make/rust-lld-by-default-beta-stable/main.rs
+++ /dev/null
@@ -1 +0,0 @@
-fn main() {}
diff --git a/tests/run-make/rust-lld-by-default-beta-stable/rmake.rs b/tests/run-make/rust-lld-by-default-beta-stable/rmake.rs
deleted file mode 100644
index 9a08991c4b8..00000000000
--- a/tests/run-make/rust-lld-by-default-beta-stable/rmake.rs
+++ /dev/null
@@ -1,14 +0,0 @@
-// Ensure that rust-lld is *not* used as the default linker on `x86_64-unknown-linux-gnu` on stable
-// or beta.
-
-//@ ignore-nightly
-//@ only-x86_64-unknown-linux-gnu
-
-use run_make_support::linker::assert_rustc_doesnt_use_lld;
-use run_make_support::rustc;
-
-fn main() {
-    // A regular compilation should not use rust-lld by default. We'll check that by asking the
-    // linker to display its version number with a link-arg.
-    assert_rustc_doesnt_use_lld(rustc().input("main.rs"));
-}
diff --git a/tests/run-make/rust-lld-custom-target/rmake.rs b/tests/run-make/rust-lld-custom-target/rmake.rs
index e2b065a10b1..90ba424ffe9 100644
--- a/tests/run-make/rust-lld-custom-target/rmake.rs
+++ b/tests/run-make/rust-lld-custom-target/rmake.rs
@@ -23,7 +23,8 @@ fn main() {
         rustc()
             .crate_type("cdylib")
             .target("custom-target.json")
-            .arg("-Zlinker-features=-lld")
+            .arg("-Clinker-features=-lld")
+            .arg("-Zunstable-options")
             .input("lib.rs"),
     );
 }
diff --git a/tests/run-make/rust-lld-link-script-provide/rmake.rs b/tests/run-make/rust-lld-link-script-provide/rmake.rs
index e78a411bc15..c637dff9038 100644
--- a/tests/run-make/rust-lld-link-script-provide/rmake.rs
+++ b/tests/run-make/rust-lld-link-script-provide/rmake.rs
@@ -10,7 +10,7 @@ use run_make_support::rustc;
 fn main() {
     rustc()
         .input("main.rs")
-        .arg("-Zlinker-features=+lld")
+        .arg("-Clinker-features=+lld")
         .arg("-Clink-self-contained=+linker")
         .arg("-Zunstable-options")
         .link_arg("-Tscript.t")
diff --git a/tests/run-make/rust-lld-by-default-nightly/main.rs b/tests/run-make/rust-lld-x86_64-unknown-linux-gnu-dist/main.rs
index e9f655fc09e..e9f655fc09e 100644
--- a/tests/run-make/rust-lld-by-default-nightly/main.rs
+++ b/tests/run-make/rust-lld-x86_64-unknown-linux-gnu-dist/main.rs
diff --git a/tests/run-make/rust-lld-by-default-nightly/rmake.rs b/tests/run-make/rust-lld-x86_64-unknown-linux-gnu-dist/rmake.rs
index 3ff1e2770e6..c315d36a39d 100644
--- a/tests/run-make/rust-lld-by-default-nightly/rmake.rs
+++ b/tests/run-make/rust-lld-x86_64-unknown-linux-gnu-dist/rmake.rs
@@ -1,19 +1,16 @@
-// Ensure that rust-lld is used as the default linker on `x86_64-unknown-linux-gnu` on the nightly
-// channel, and that it can also be turned off with a CLI flag.
+// Ensure that rust-lld is used as the default linker on `x86_64-unknown-linux-gnu`
+// dist artifacts and that it can also be turned off with a CLI flag.
 
-//@ needs-rust-lld
-//@ ignore-beta
-//@ ignore-stable
+//@ only-dist
 //@ only-x86_64-unknown-linux-gnu
 
 use run_make_support::linker::{assert_rustc_doesnt_use_lld, assert_rustc_uses_lld};
 use run_make_support::rustc;
 
 fn main() {
-    // A regular compilation should use rust-lld by default. We'll check that by asking the linker
-    // to display its version number with a link-arg.
+    // A regular compilation should use rust-lld by default.
     assert_rustc_uses_lld(rustc().input("main.rs"));
 
     // But it can still be disabled by turning the linker feature off.
-    assert_rustc_doesnt_use_lld(rustc().arg("-Zlinker-features=-lld").input("main.rs"));
+    assert_rustc_doesnt_use_lld(rustc().arg("-Clinker-features=-lld").input("main.rs"));
 }
diff --git a/tests/run-make/rust-lld-x86_64-unknown-linux-gnu/main.rs b/tests/run-make/rust-lld-x86_64-unknown-linux-gnu/main.rs
new file mode 100644
index 00000000000..e9f655fc09e
--- /dev/null
+++ b/tests/run-make/rust-lld-x86_64-unknown-linux-gnu/main.rs
@@ -0,0 +1,5 @@
+// Test linking using `cc` with `rust-lld`, which is on by default on the x86_64-unknown-linux-gnu
+// target.
+// See https://github.com/rust-lang/compiler-team/issues/510 for more info
+
+fn main() {}
diff --git a/tests/run-make/rust-lld-x86_64-unknown-linux-gnu/rmake.rs b/tests/run-make/rust-lld-x86_64-unknown-linux-gnu/rmake.rs
new file mode 100644
index 00000000000..00415d27aaf
--- /dev/null
+++ b/tests/run-make/rust-lld-x86_64-unknown-linux-gnu/rmake.rs
@@ -0,0 +1,20 @@
+// Ensure that rust-lld is used as the default linker on `x86_64-unknown-linux-gnu`
+// and that it can also be turned off with a CLI flag.
+//
+// This version of the test checks that LLD is used by default when LLD is enabled in the
+// toolchain. There is a separate test that checks that LLD is used for dist artifacts
+// unconditionally.
+
+//@ needs-rust-lld
+//@ only-x86_64-unknown-linux-gnu
+
+use run_make_support::linker::{assert_rustc_doesnt_use_lld, assert_rustc_uses_lld};
+use run_make_support::rustc;
+
+fn main() {
+    // A regular compilation should use rust-lld by default.
+    assert_rustc_uses_lld(rustc().input("main.rs"));
+
+    // But it can still be disabled by turning the linker feature off.
+    assert_rustc_doesnt_use_lld(rustc().arg("-Clinker-features=-lld").input("main.rs"));
+}
diff --git a/tests/run-make/rust-lld/rmake.rs b/tests/run-make/rust-lld/rmake.rs
index 9470f5d0be1..932c2697ba0 100644
--- a/tests/run-make/rust-lld/rmake.rs
+++ b/tests/run-make/rust-lld/rmake.rs
@@ -1,5 +1,5 @@
-// Test linking using `cc` with `rust-lld`, using the unstable CLI described in MCP 510
-// see https://github.com/rust-lang/compiler-team/issues/510 for more info
+// Test linking using `cc` with `rust-lld`, using the `-Clinker-features` and
+// `-Clink-self-contained` CLI flags.
 
 //@ needs-rust-lld
 //@ ignore-s390x lld does not yet support s390x as target
@@ -12,14 +12,16 @@ fn main() {
     // asking the linker to display its version number with a link-arg.
     assert_rustc_uses_lld(
         rustc()
-            .arg("-Zlinker-features=+lld")
+            .arg("-Clinker-features=+lld")
             .arg("-Clink-self-contained=+linker")
-            .arg("-Zunstable-options")
+            .arg("-Zunstable-options") // the opt-ins are unstable
             .input("main.rs"),
     );
 
     // It should not be used when we explicitly opt out of lld.
-    assert_rustc_doesnt_use_lld(rustc().arg("-Zlinker-features=-lld").input("main.rs"));
+    assert_rustc_doesnt_use_lld(
+        rustc().arg("-Clinker-features=-lld").arg("-Zunstable-options").input("main.rs"),
+    );
 
     // While we're here, also check that the last linker feature flag "wins" when passed multiple
     // times to rustc.
@@ -27,9 +29,9 @@ fn main() {
         rustc()
             .arg("-Clink-self-contained=+linker")
             .arg("-Zunstable-options")
-            .arg("-Zlinker-features=-lld")
-            .arg("-Zlinker-features=+lld")
-            .arg("-Zlinker-features=-lld,+lld")
+            .arg("-Clinker-features=-lld")
+            .arg("-Clinker-features=+lld")
+            .arg("-Clinker-features=-lld,+lld")
             .input("main.rs"),
     );
 }
diff --git a/tests/ui/linking/link-self-contained-consistency.rs b/tests/ui/linking/link-self-contained-consistency.rs
index 08227433891..e3944fc0360 100644
--- a/tests/ui/linking/link-self-contained-consistency.rs
+++ b/tests/ui/linking/link-self-contained-consistency.rs
@@ -1,7 +1,6 @@
 // Checks that self-contained linking components cannot be both enabled and disabled at the same
 // time on the CLI.
 
-//@ check-fail
 //@ revisions: one many
 //@ [one] compile-flags: -Clink-self-contained=-linker -Clink-self-contained=+linker -Zunstable-options
 //@ [many] compile-flags: -Clink-self-contained=+linker,+crto -Clink-self-contained=-linker,-crto -Zunstable-options
diff --git a/tests/ui/linking/link-self-contained-linker-disallowed.rs b/tests/ui/linking/link-self-contained-linker-disallowed.rs
new file mode 100644
index 00000000000..f076eb2017a
--- /dev/null
+++ b/tests/ui/linking/link-self-contained-linker-disallowed.rs
@@ -0,0 +1,18 @@
+// Check that only `-C link-self-contained=-linker` is stable on x64 linux. Any other value or
+// target, needs `-Z unstable-options`.
+
+// ignore-tidy-linelength
+
+//@ revisions: unstable_target_positive unstable_target_negative unstable_positive
+//@ [unstable_target_negative] compile-flags: --target=x86_64-unknown-linux-musl -C link-self-contained=-linker --crate-type=rlib
+//@ [unstable_target_negative] needs-llvm-components: x86
+//@ [unstable_target_positive] compile-flags: --target=x86_64-unknown-linux-musl -C link-self-contained=+linker --crate-type=rlib
+//@ [unstable_target_positive] needs-llvm-components: x86
+//@ [unstable_positive] compile-flags: --target=x86_64-unknown-linux-gnu -C link-self-contained=+linker --crate-type=rlib
+//@ [unstable_positive] needs-llvm-components: x86
+
+#![feature(no_core)]
+#![no_core]
+
+//[unstable_target_negative]~? ERROR `-C link-self-contained=-linker` is unstable on the `x86_64-unknown-linux-musl` target
+//[unstable_target_positive,unstable_positive]~? ERROR only `-C link-self-contained` values `y`/`yes`/`on`/`n`/`no`/`off`/`-linker` are stable
diff --git a/tests/ui/linking/link-self-contained-linker-disallowed.unstable_positive.stderr b/tests/ui/linking/link-self-contained-linker-disallowed.unstable_positive.stderr
new file mode 100644
index 00000000000..4eb0ff04b65
--- /dev/null
+++ b/tests/ui/linking/link-self-contained-linker-disallowed.unstable_positive.stderr
@@ -0,0 +1,2 @@
+error: only `-C link-self-contained` values `y`/`yes`/`on`/`n`/`no`/`off`/`-linker` are stable, the `-Z unstable-options` flag must also be passed to use the unstable values
+
diff --git a/tests/ui/linking/link-self-contained-linker-disallowed.unstable_target_negative.stderr b/tests/ui/linking/link-self-contained-linker-disallowed.unstable_target_negative.stderr
new file mode 100644
index 00000000000..8bf71941c44
--- /dev/null
+++ b/tests/ui/linking/link-self-contained-linker-disallowed.unstable_target_negative.stderr
@@ -0,0 +1,2 @@
+error: `-C link-self-contained=-linker` is unstable on the `x86_64-unknown-linux-musl` target. The `-Z unstable-options` flag must also be passed to use it on this target
+
diff --git a/tests/ui/linking/link-self-contained-linker-disallowed.unstable_target_positive.stderr b/tests/ui/linking/link-self-contained-linker-disallowed.unstable_target_positive.stderr
new file mode 100644
index 00000000000..4eb0ff04b65
--- /dev/null
+++ b/tests/ui/linking/link-self-contained-linker-disallowed.unstable_target_positive.stderr
@@ -0,0 +1,2 @@
+error: only `-C link-self-contained` values `y`/`yes`/`on`/`n`/`no`/`off`/`-linker` are stable, the `-Z unstable-options` flag must also be passed to use the unstable values
+
diff --git a/tests/ui/linking/link-self-contained-unstable.crto.stderr b/tests/ui/linking/link-self-contained-unstable.crto.stderr
new file mode 100644
index 00000000000..4eb0ff04b65
--- /dev/null
+++ b/tests/ui/linking/link-self-contained-unstable.crto.stderr
@@ -0,0 +1,2 @@
+error: only `-C link-self-contained` values `y`/`yes`/`on`/`n`/`no`/`off`/`-linker` are stable, the `-Z unstable-options` flag must also be passed to use the unstable values
+
diff --git a/tests/ui/linking/link-self-contained-unstable.libc.stderr b/tests/ui/linking/link-self-contained-unstable.libc.stderr
new file mode 100644
index 00000000000..4eb0ff04b65
--- /dev/null
+++ b/tests/ui/linking/link-self-contained-unstable.libc.stderr
@@ -0,0 +1,2 @@
+error: only `-C link-self-contained` values `y`/`yes`/`on`/`n`/`no`/`off`/`-linker` are stable, the `-Z unstable-options` flag must also be passed to use the unstable values
+
diff --git a/tests/ui/linking/link-self-contained-unstable.mingw.stderr b/tests/ui/linking/link-self-contained-unstable.mingw.stderr
new file mode 100644
index 00000000000..4eb0ff04b65
--- /dev/null
+++ b/tests/ui/linking/link-self-contained-unstable.mingw.stderr
@@ -0,0 +1,2 @@
+error: only `-C link-self-contained` values `y`/`yes`/`on`/`n`/`no`/`off`/`-linker` are stable, the `-Z unstable-options` flag must also be passed to use the unstable values
+
diff --git a/tests/ui/linking/link-self-contained-unstable.rs b/tests/ui/linking/link-self-contained-unstable.rs
new file mode 100644
index 00000000000..10c895909d5
--- /dev/null
+++ b/tests/ui/linking/link-self-contained-unstable.rs
@@ -0,0 +1,13 @@
+// Checks that values for `-Clink-self-contained` other than the blanket enable/disable and
+// `-linker` require `-Zunstable-options`.
+
+//@ revisions: crto libc unwind sanitizers mingw
+//@ [crto] compile-flags: -Clink-self-contained=+crto
+//@ [libc] compile-flags: -Clink-self-contained=-libc
+//@ [unwind] compile-flags: -Clink-self-contained=+unwind
+//@ [sanitizers] compile-flags: -Clink-self-contained=-sanitizers
+//@ [mingw] compile-flags: -Clink-self-contained=+mingw
+
+fn main() {}
+
+//~? ERROR only `-C link-self-contained` values `y`/`yes`/`on`/`n`/`no`/`off`/`-linker` are stable
diff --git a/tests/ui/linking/link-self-contained-unstable.sanitizers.stderr b/tests/ui/linking/link-self-contained-unstable.sanitizers.stderr
new file mode 100644
index 00000000000..4eb0ff04b65
--- /dev/null
+++ b/tests/ui/linking/link-self-contained-unstable.sanitizers.stderr
@@ -0,0 +1,2 @@
+error: only `-C link-self-contained` values `y`/`yes`/`on`/`n`/`no`/`off`/`-linker` are stable, the `-Z unstable-options` flag must also be passed to use the unstable values
+
diff --git a/tests/ui/linking/link-self-contained-unstable.unwind.stderr b/tests/ui/linking/link-self-contained-unstable.unwind.stderr
new file mode 100644
index 00000000000..4eb0ff04b65
--- /dev/null
+++ b/tests/ui/linking/link-self-contained-unstable.unwind.stderr
@@ -0,0 +1,2 @@
+error: only `-C link-self-contained` values `y`/`yes`/`on`/`n`/`no`/`off`/`-linker` are stable, the `-Z unstable-options` flag must also be passed to use the unstable values
+
diff --git a/tests/ui/linking/linker-features-lld-disallowed.rs b/tests/ui/linking/linker-features-lld-disallowed.rs
new file mode 100644
index 00000000000..9b8fa2b11e6
--- /dev/null
+++ b/tests/ui/linking/linker-features-lld-disallowed.rs
@@ -0,0 +1,19 @@
+// Check that only `-C linker-features=-lld` is stable on x64 linux. Any other value or target,
+// needs `-Z unstable-options`.
+
+// ignore-tidy-linelength
+
+//@ revisions: unstable_target_positive unstable_target_negative unstable_positive
+//@ [unstable_target_negative] compile-flags: --target=x86_64-unknown-linux-musl -C linker-features=-lld --crate-type=rlib
+//@ [unstable_target_negative] needs-llvm-components: x86
+//@ [unstable_target_positive] compile-flags: --target=x86_64-unknown-linux-musl -C linker-features=+lld --crate-type=rlib
+//@ [unstable_target_positive] needs-llvm-components: x86
+//@ [unstable_positive] compile-flags: --target=x86_64-unknown-linux-gnu -C linker-features=+lld --crate-type=rlib
+//@ [unstable_positive] needs-llvm-components: x86
+
+
+#![feature(no_core)]
+#![no_core]
+
+//[unstable_target_negative]~? ERROR `-C linker-features=-lld` is unstable on the `x86_64-unknown-linux-musl` target
+//[unstable_target_positive,unstable_positive]~? ERROR `-C linker-features=+lld` is unstable, and also requires the `-Z unstable-options`
diff --git a/tests/ui/linking/linker-features-lld-disallowed.unstable_positive.stderr b/tests/ui/linking/linker-features-lld-disallowed.unstable_positive.stderr
new file mode 100644
index 00000000000..09e7e4975c4
--- /dev/null
+++ b/tests/ui/linking/linker-features-lld-disallowed.unstable_positive.stderr
@@ -0,0 +1,2 @@
+error: `-C linker-features=+lld` is unstable, and also requires the `-Z unstable-options` flag to be used
+
diff --git a/tests/ui/linking/linker-features-lld-disallowed.unstable_target_negative.stderr b/tests/ui/linking/linker-features-lld-disallowed.unstable_target_negative.stderr
new file mode 100644
index 00000000000..205082b0726
--- /dev/null
+++ b/tests/ui/linking/linker-features-lld-disallowed.unstable_target_negative.stderr
@@ -0,0 +1,2 @@
+error: `-C linker-features=-lld` is unstable on the `x86_64-unknown-linux-musl` target. The `-Z unstable-options` flag must also be passed to use it on this target
+
diff --git a/tests/ui/linking/linker-features-lld-disallowed.unstable_target_positive.stderr b/tests/ui/linking/linker-features-lld-disallowed.unstable_target_positive.stderr
new file mode 100644
index 00000000000..09e7e4975c4
--- /dev/null
+++ b/tests/ui/linking/linker-features-lld-disallowed.unstable_target_positive.stderr
@@ -0,0 +1,2 @@
+error: `-C linker-features=+lld` is unstable, and also requires the `-Z unstable-options` flag to be used
+
diff --git a/tests/ui/linking/linker-features-malformed.invalid_modifier.stderr b/tests/ui/linking/linker-features-malformed.invalid_modifier.stderr
index 909b277089f..d9ed65ad3e2 100644
--- a/tests/ui/linking/linker-features-malformed.invalid_modifier.stderr
+++ b/tests/ui/linking/linker-features-malformed.invalid_modifier.stderr
@@ -1,2 +1,2 @@
-error: incorrect value `*lld` for unstable option `linker-features` - a list of enabled (`+` prefix) and disabled (`-` prefix) features: `lld` was expected
+error: incorrect value `*lld` for codegen option `linker-features` - a list of enabled (`+` prefix) and disabled (`-` prefix) features: `lld` was expected
 
diff --git a/tests/ui/linking/linker-features-malformed.invalid_separator.stderr b/tests/ui/linking/linker-features-malformed.invalid_separator.stderr
index 0f84898a774..e950d8f3e8f 100644
--- a/tests/ui/linking/linker-features-malformed.invalid_separator.stderr
+++ b/tests/ui/linking/linker-features-malformed.invalid_separator.stderr
@@ -1,2 +1,2 @@
-error: incorrect value `-lld@+lld` for unstable option `linker-features` - a list of enabled (`+` prefix) and disabled (`-` prefix) features: `lld` was expected
+error: incorrect value `-lld@+lld` for codegen option `linker-features` - a list of enabled (`+` prefix) and disabled (`-` prefix) features: `lld` was expected
 
diff --git a/tests/ui/linking/linker-features-malformed.no_value.stderr b/tests/ui/linking/linker-features-malformed.no_value.stderr
index e93a4e79bb1..e03d3b34bb1 100644
--- a/tests/ui/linking/linker-features-malformed.no_value.stderr
+++ b/tests/ui/linking/linker-features-malformed.no_value.stderr
@@ -1,2 +1,2 @@
-error: incorrect value `` for unstable option `linker-features` - a list of enabled (`+` prefix) and disabled (`-` prefix) features: `lld` was expected
+error: incorrect value `` for codegen option `linker-features` - a list of enabled (`+` prefix) and disabled (`-` prefix) features: `lld` was expected
 
diff --git a/tests/ui/linking/linker-features-malformed.rs b/tests/ui/linking/linker-features-malformed.rs
index 0bdcfa39920..627b8e68920 100644
--- a/tests/ui/linking/linker-features-malformed.rs
+++ b/tests/ui/linking/linker-features-malformed.rs
@@ -1,27 +1,27 @@
-//! Check that malformed `-Zlinker-features` flags are properly rejected.
+//! Check that malformed `-Clinker-features` flags are properly rejected.
 
 //@ revisions: no_value
-//@[no_value] compile-flags: -Zlinker-features=
-//[no_value]~? ERROR incorrect value `` for unstable option `linker-features`
+//@[no_value] compile-flags: -Clinker-features=
+//[no_value]~? ERROR incorrect value `` for codegen option `linker-features`
 
 //@ revisions: invalid_modifier
-//@[invalid_modifier] compile-flags: -Zlinker-features=*lld
-//[invalid_modifier]~? ERROR incorrect value `*lld` for unstable option `linker-features`
+//@[invalid_modifier] compile-flags: -Clinker-features=*lld
+//[invalid_modifier]~? ERROR incorrect value `*lld` for codegen option `linker-features`
 
 //@ revisions: unknown_value
-//@[unknown_value] compile-flags: -Zlinker-features=unknown
-//[unknown_value]~? ERROR incorrect value `unknown` for unstable option `linker-features`
+//@[unknown_value] compile-flags: -Clinker-features=unknown
+//[unknown_value]~? ERROR incorrect value `unknown` for codegen option `linker-features`
 
 //@ revisions: unknown_modifier_value
-//@[unknown_modifier_value] compile-flags: -Zlinker-features=-unknown
-//[unknown_modifier_value]~? ERROR incorrect value `-unknown` for unstable option `linker-features`
+//@[unknown_modifier_value] compile-flags: -Clinker-features=-unknown
+//[unknown_modifier_value]~? ERROR incorrect value `-unknown` for codegen option `linker-features`
 
 //@ revisions: unknown_boolean
-//@[unknown_boolean] compile-flags: -Zlinker-features=maybe
-//[unknown_boolean]~? ERROR incorrect value `maybe` for unstable option `linker-features`
+//@[unknown_boolean] compile-flags: -Clinker-features=maybe
+//[unknown_boolean]~? ERROR incorrect value `maybe` for codegen option `linker-features`
 
 //@ revisions: invalid_separator
-//@[invalid_separator] compile-flags: -Zlinker-features=-lld@+lld
-//[invalid_separator]~? ERROR incorrect value `-lld@+lld` for unstable option `linker-features`
+//@[invalid_separator] compile-flags: -Clinker-features=-lld@+lld
+//[invalid_separator]~? ERROR incorrect value `-lld@+lld` for codegen option `linker-features`
 
 fn main() {}
diff --git a/tests/ui/linking/linker-features-malformed.unknown_boolean.stderr b/tests/ui/linking/linker-features-malformed.unknown_boolean.stderr
index 865738d0ccc..d82c2ea04b4 100644
--- a/tests/ui/linking/linker-features-malformed.unknown_boolean.stderr
+++ b/tests/ui/linking/linker-features-malformed.unknown_boolean.stderr
@@ -1,2 +1,2 @@
-error: incorrect value `maybe` for unstable option `linker-features` - a list of enabled (`+` prefix) and disabled (`-` prefix) features: `lld` was expected
+error: incorrect value `maybe` for codegen option `linker-features` - a list of enabled (`+` prefix) and disabled (`-` prefix) features: `lld` was expected
 
diff --git a/tests/ui/linking/linker-features-malformed.unknown_modifier_value.stderr b/tests/ui/linking/linker-features-malformed.unknown_modifier_value.stderr
index 03b9620ca26..59366e28e44 100644
--- a/tests/ui/linking/linker-features-malformed.unknown_modifier_value.stderr
+++ b/tests/ui/linking/linker-features-malformed.unknown_modifier_value.stderr
@@ -1,2 +1,2 @@
-error: incorrect value `-unknown` for unstable option `linker-features` - a list of enabled (`+` prefix) and disabled (`-` prefix) features: `lld` was expected
+error: incorrect value `-unknown` for codegen option `linker-features` - a list of enabled (`+` prefix) and disabled (`-` prefix) features: `lld` was expected
 
diff --git a/tests/ui/linking/linker-features-malformed.unknown_value.stderr b/tests/ui/linking/linker-features-malformed.unknown_value.stderr
index 566632a3df3..e8f6d5e637c 100644
--- a/tests/ui/linking/linker-features-malformed.unknown_value.stderr
+++ b/tests/ui/linking/linker-features-malformed.unknown_value.stderr
@@ -1,2 +1,2 @@
-error: incorrect value `unknown` for unstable option `linker-features` - a list of enabled (`+` prefix) and disabled (`-` prefix) features: `lld` was expected
+error: incorrect value `unknown` for codegen option `linker-features` - a list of enabled (`+` prefix) and disabled (`-` prefix) features: `lld` was expected
 
diff --git a/tests/ui/linking/linker-features-unstable-cc.rs b/tests/ui/linking/linker-features-unstable-cc.rs
new file mode 100644
index 00000000000..38103c81060
--- /dev/null
+++ b/tests/ui/linking/linker-features-unstable-cc.rs
@@ -0,0 +1,13 @@
+// Check that only `-C linker-features=-lld` is stable on x64 linux, and that other linker
+// features require using `-Z unstable-options`.
+//
+// Note that, currently, only `lld` is parsed on the CLI, but that other linker features can exist
+// internally (`cc`).
+//
+//@ compile-flags: --target=x86_64-unknown-linux-gnu -C linker-features=+cc --crate-type=rlib
+//@ needs-llvm-components: x86
+
+#![feature(no_core)]
+#![no_core]
+
+//~? ERROR incorrect value `+cc` for codegen option `linker-features`
diff --git a/tests/ui/linking/linker-features-unstable-cc.stderr b/tests/ui/linking/linker-features-unstable-cc.stderr
new file mode 100644
index 00000000000..a69b4198160
--- /dev/null
+++ b/tests/ui/linking/linker-features-unstable-cc.stderr
@@ -0,0 +1,2 @@
+error: incorrect value `+cc` for codegen option `linker-features` - a list of enabled (`+` prefix) and disabled (`-` prefix) features: `lld` was expected
+