self-contained linker: conservatively default to `-znostart-stop-gc` on x64 linux #137685

lqd · 2025-02-26T16:59:59Z

To help stabilization, this PR disables an LLD optimization on x64 linux with respect to --gc-sections and encapsulation symbols: it will reduce the number of crates needing to opt-out of lld due to this bfd / lld difference. For example, all the people using linkme, which doesn't work with lld or on nightly, need to disable lld.

More information about all this, and the historical differences, can be found in:

This optimization has no visible impact on our benchmarks, so we can use it by default and have a safer/more conservative starting point to remove friction during migration. We can them emit an FCW for the cases where lld detects reliance on encapsulation symbols without -znostart-stop-gc, and then revert back to lld's default after a while. No one compiling on nightly relies on this difference, obviously, so doing an FCW is not necessary until after lld is used on stable.

I've tested that this correctly links on linkme examples. I've also quickly tried to crate an rmake test but the setup with encapsulation symbols is annoying to reproduce: a few link section/name attributes is not enough, we also need to collect symbols between the encapsulation symbols, without referencing them in code, for -znostart-stop-gc to only impact this... It should of course be doable though, maybe @Kobzol will look into it if they have time.

r? @petrochenkov

lqd · 2025-02-26T17:09:48Z

Sanity check perf run:

@bors try @rust-timer queue

self-contained linker: conservatively default to `-znostart-stop-gc` To help stabilization, this PR disables an LLD optimization with respect to `--gc-sections` and encapsulation symbols: it will reduce the number of crates needing to opt-out of lld due to this bfd / lld difference. For example, all the people using [linkme](https://github.com/dtolnay/linkme), which [doesn't work with lld](dtolnay/linkme#63) or on nightly, need to disable lld. This optimization has [no visible impact](rust-lang#112049 (comment)) on our benchmarks, so we can use it by default and have a safer/more conservative starting point to remove friction during migration. We can them emit an FCW for the cases where lld detects reliance on encapsulation symbols without `-znostart-stop-gc`, and then revert back to lld's default after a while. No one compiling on nightly relies on this difference, obviously, so doing an FCW is not necessary until after lld is used on stable. I've tested that this correctly links on `linkme` examples. I've also quickly tried to crate an rmake test but the setup with encapsulation symbols is annoying to reproduce: a few link section/name attributes is not enough, we also need to collect symbols between the encapsulation symbols, without referencing them in code, for `-znostart-stop-gc` to only impact this... It should of course be doable though, maybe `@Kobzol` will look into it if they have time. r? `@petrochenkov`

bors · 2025-02-26T17:10:59Z

⌛ Trying commit 762fdf6 with merge ced69ff...

bors · 2025-02-26T19:09:36Z

☀️ Try build successful - checks-actions
Build commit: ced69ff (ced69fff94a2a0d15512ca568f4fd890ebcc4f23)

rust-timer · 2025-02-26T20:26:34Z

Finished benchmarking commit (ced69ff): comparison URL.

Overall result: no relevant changes - no action needed

Benchmarking this pull request likely means that it is perf-sensitive, so we're automatically marking it as not fit for rolling up. While you can manually mark this PR as fit for rollup, we strongly recommend not doing so since this PR may lead to changes in compiler perf.

@bors rollup=never
@rustbot label: -S-waiting-on-perf -perf-regression

Instruction count

This benchmark run did not return any relevant results for this metric.

Max RSS (memory usage)

Results (primary 3.4%, secondary -2.2%)

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	3.4%	[3.4%, 3.4%]	1
Regressions ❌ (secondary)	-	-	0
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-2.2%	[-2.2%, -2.2%]	1
All ❌✅ (primary)	3.4%	[3.4%, 3.4%]	1

Cycles

Results (secondary 1.7%)

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	1.7%	[1.7%, 1.7%]	1
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	-	-	0

Binary size

This benchmark run did not return any relevant results for this metric.

Bootstrap: 771.284s -> 771.237s (-0.01%)
Artifact size: 361.94 MiB -> 361.93 MiB (-0.00%)

mati865 · 2025-02-27T07:45:26Z

Even better than emitting FCWs would be fixing LLD. Wild linker had the same issue, but the fix was quite easy: davidlattimore/wild#460

Kobzol · 2025-02-27T07:48:29Z

LLD has said on several occasions that they won't fix this, as they don't consider it to be an issue (https://lld.llvm.org/ELF/start-stop-gc.html). We're kind of being overly conservative here.

lqd · 2025-02-27T11:07:16Z

Even better than emitting FCWs would be fixing LLD

To be clear, there is nothing to fix in either linkers per se: they both implement the two behaviors of conservative and precise GC. The default value is just different, GNU ld defaults to -z nostart-stop-gc while lld now defaults to -z start-stop-gc.

It's more of a difference of opinion, which is why I described this as disabling a size optimization. It just helps stabilization, to remove a concern of these different defaults, and delay possible FCWs and wait periods to where it's needed.

We could equally do nothing and take the breakage.

petrochenkov · 2025-02-27T18:05:21Z

@bors r+

bors · 2025-02-27T18:05:24Z

📌 Commit 762fdf6 has been approved by petrochenkov

It is now in the queue for this repository.

bors · 2025-02-27T18:05:25Z

🌲 The tree is currently closed for pull requests below priority 100. This pull request will be tested once the tree is reopened.

compiler-errors · 2025-03-01T19:55:25Z

@bors rollup-

self-contained linker: conservatively default to `-znostart-stop-gc` To help stabilization, this PR disables an LLD optimization with respect to `--gc-sections` and encapsulation symbols: it will reduce the number of crates needing to opt-out of lld due to this bfd / lld difference. For example, all the people using [linkme](https://github.com/dtolnay/linkme), which [doesn't work with lld](dtolnay/linkme#63) or on nightly, need to disable lld. More information about all this, and the historical differences, 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 This optimization has [no visible impact](rust-lang#137685 (comment)) on our benchmarks, so we can use it by default and have a safer/more conservative starting point to remove friction during migration. We can them emit an FCW for the cases where lld detects reliance on encapsulation symbols without `-znostart-stop-gc`, and then revert back to lld's default after a while. No one compiling on nightly relies on this difference, obviously, so doing an FCW is not necessary until after lld is used on stable. I've tested that this correctly links on `linkme` examples. I've also quickly tried to crate an rmake test but the setup with encapsulation symbols is annoying to reproduce: a few link section/name attributes is not enough, we also need to collect symbols between the encapsulation symbols, without referencing them in code, for `-znostart-stop-gc` to only impact this... It should of course be doable though, maybe `@Kobzol` will look into it if they have time. r? `@petrochenkov`

self-contained linker: conservatively default to `-znostart-stop-gc` To help stabilization, this PR disables an LLD optimization with respect to `--gc-sections` and encapsulation symbols: it will reduce the number of crates needing to opt-out of lld due to this bfd / lld difference. For example, all the people using [linkme](https://github.com/dtolnay/linkme), which [doesn't work with lld](dtolnay/linkme#63) or on nightly, need to disable lld. More information about all this, and the historical differences, 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 This optimization has [no visible impact](rust-lang#137685 (comment)) on our benchmarks, so we can use it by default and have a safer/more conservative starting point to remove friction during migration. We can them emit an FCW for the cases where lld detects reliance on encapsulation symbols without `-znostart-stop-gc`, and then revert back to lld's default after a while. No one compiling on nightly relies on this difference, obviously, so doing an FCW is not necessary until after lld is used on stable. I've tested that this correctly links on `linkme` examples. I've also quickly tried to crate an rmake test but the setup with encapsulation symbols is annoying to reproduce: a few link section/name attributes is not enough, we also need to collect symbols between the encapsulation symbols, without referencing them in code, for `-znostart-stop-gc` to only impact this... It should of course be doable though, maybe ``@Kobzol`` will look into it if they have time. r? ``@petrochenkov``

self-contained linker: conservatively default to `-znostart-stop-gc` To help stabilization, this PR disables an LLD optimization with respect to `--gc-sections` and encapsulation symbols: it will reduce the number of crates needing to opt-out of lld due to this bfd / lld difference. For example, all the people using [linkme](https://github.com/dtolnay/linkme), which [doesn't work with lld](dtolnay/linkme#63) or on nightly, need to disable lld. More information about all this, and the historical differences, 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 This optimization has [no visible impact](rust-lang#137685 (comment)) on our benchmarks, so we can use it by default and have a safer/more conservative starting point to remove friction during migration. We can them emit an FCW for the cases where lld detects reliance on encapsulation symbols without `-znostart-stop-gc`, and then revert back to lld's default after a while. No one compiling on nightly relies on this difference, obviously, so doing an FCW is not necessary until after lld is used on stable. I've tested that this correctly links on `linkme` examples. I've also quickly tried to crate an rmake test but the setup with encapsulation symbols is annoying to reproduce: a few link section/name attributes is not enough, we also need to collect symbols between the encapsulation symbols, without referencing them in code, for `-znostart-stop-gc` to only impact this... It should of course be doable though, maybe ```@Kobzol``` will look into it if they have time. r? ```@petrochenkov```

…iaskrgr Rollup of 10 pull requests Successful merges: - rust-lang#132388 (Implement `#[cfg]` in `where` clauses) - rust-lang#134900 (Fix parsing of ranges after unary operators) - rust-lang#136938 (Remove `:` from `stack-protector-heuristics-effect.rs` Filecheck Pattern) - rust-lang#137054 (Make phantom variance markers transparent) - rust-lang#137525 (Simplify parallelization in test-float-parse) - rust-lang#137618 (Skip `tidy` in pre-push hook if the user is deleting a remote branch) - rust-lang#137685 (self-contained linker: conservatively default to `-znostart-stop-gc`) - rust-lang#137741 (Stop using `hash_raw_entry` in `CodegenCx::const_str`) - rust-lang#137849 (Revert "Remove Win SDK 10.0.26100.0 from CI") - rust-lang#137862 (ensure we always print all --print options in help) r? `@ghost` `@rustbot` modify labels: rollup

petrochenkov · 2025-03-05T15:37:48Z

@bors r+

bors · 2025-03-05T15:37:51Z

📌 Commit e0b7577 has been approved by petrochenkov

It is now in the queue for this repository.

self-contained linker: conservatively default to `-znostart-stop-gc` on x64 linux To help stabilization, this PR disables an LLD optimization on x64 linux with respect to `--gc-sections` and encapsulation symbols: it will reduce the number of crates needing to opt-out of lld due to this bfd / lld difference. For example, all the people using [linkme](https://github.com/dtolnay/linkme), which [doesn't work with lld](dtolnay/linkme#63) or on nightly, need to disable lld. More information about all this, and the historical differences, 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 This optimization has [no visible impact](rust-lang#137685 (comment)) on our benchmarks, so we can use it by default and have a safer/more conservative starting point to remove friction during migration. We can them emit an FCW for the cases where lld detects reliance on encapsulation symbols without `-znostart-stop-gc`, and then revert back to lld's default after a while. No one compiling on nightly relies on this difference, obviously, so doing an FCW is not necessary until after lld is used on stable. I've tested that this correctly links on `linkme` examples. I've also quickly tried to crate an rmake test but the setup with encapsulation symbols is annoying to reproduce: a few link section/name attributes is not enough, we also need to collect symbols between the encapsulation symbols, without referencing them in code, for `-znostart-stop-gc` to only impact this... It should of course be doable though, maybe `@Kobzol` will look into it if they have time. r? `@petrochenkov`

Rollup of 29 pull requests Successful merges: - rust-lang#135733 (Implement `&pin const self` and `&pin mut self` sugars) - rust-lang#137107 (Override default `Write` methods for cursor-like types) - rust-lang#137303 (Remove `MaybeForgetReturn` suggestion) - rust-lang#137327 (Undeprecate env::home_dir) - rust-lang#137358 (Match Ergonomics 2024: add context and examples to the unstable book) - rust-lang#137534 ([rustdoc] hide item that is not marked as doc(inline) and whose src is doc(hidden)) - rust-lang#137565 (Try to point of macro expansion from resolver and method errors if it involves macro var) - rust-lang#137612 (Update bootstrap to edition 2024) - rust-lang#137637 (Check dyn flavor before registering upcast goal on wide pointer cast in MIR typeck) - rust-lang#137643 (Add DWARF test case for non-C-like `repr128` enums) - rust-lang#137685 (self-contained linker: conservatively default to `-znostart-stop-gc` on x64 linux) - rust-lang#137744 (Re-add `Clone`-derive on `Thir`) - rust-lang#137758 (fix usage of ty decl macro fragments in attributes) - rust-lang#137764 (Ensure that negative auto impls are always applicable) - rust-lang#137772 (Fix char count in `Display` for `ByteStr`) - rust-lang#137798 (ci: use ubuntu 24 on arm large runner) - rust-lang#137802 (miri native-call support: all previously exposed provenance is accessible to the callee) - rust-lang#137805 (adjust Layout debug printing to match the internal field name) - rust-lang#137808 (Do not require that unsafe fields lack drop glue) - rust-lang#137820 (Clarify why InhabitedPredicate::instantiate_opt exists) - rust-lang#137825 (Provide more context on resolve error caused from incorrect RTN) - rust-lang#137827 (Add timestamp to unstable feature usage metrics) - rust-lang#137832 (Fix crash in BufReader::peek()) - rust-lang#137910 (Improve error message for `AsyncFn` trait failure for RPIT) - rust-lang#137920 (interpret/provenance_map: consistently use range_is_empty) - rust-lang#138038 (Update `compiler-builtins` to 0.1.151) - rust-lang#138046 (trim channel value in `get_closest_merge_commit`) - rust-lang#138052 (strip `-Wlinker-messages` wrappers from `rust-lld` rmake test) - rust-lang#138053 (Increase the max. custom try jobs requested to `20`) r? `@ghost` `@rustbot` modify labels: rollup

self-contained linker: conservatively default to `-znostart-stop-gc` on x64 linux To help stabilization, this PR disables an LLD optimization on x64 linux with respect to `--gc-sections` and encapsulation symbols: it will reduce the number of crates needing to opt-out of lld due to this bfd / lld difference. For example, all the people using [linkme](https://github.com/dtolnay/linkme), which [doesn't work with lld](dtolnay/linkme#63) or on nightly, need to disable lld. More information about all this, and the historical differences, 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 This optimization has [no visible impact](rust-lang#137685 (comment)) on our benchmarks, so we can use it by default and have a safer/more conservative starting point to remove friction during migration. We can them emit an FCW for the cases where lld detects reliance on encapsulation symbols without `-znostart-stop-gc`, and then revert back to lld's default after a while. No one compiling on nightly relies on this difference, obviously, so doing an FCW is not necessary until after lld is used on stable. I've tested that this correctly links on `linkme` examples. I've also quickly tried to crate an rmake test but the setup with encapsulation symbols is annoying to reproduce: a few link section/name attributes is not enough, we also need to collect symbols between the encapsulation symbols, without referencing them in code, for `-znostart-stop-gc` to only impact this... It should of course be doable though, maybe ``@Kobzol`` will look into it if they have time. r? ``@petrochenkov``

self-contained linker: conservatively default to `-znostart-stop-gc` on x64 linux To help stabilization, this PR disables an LLD optimization on x64 linux with respect to `--gc-sections` and encapsulation symbols: it will reduce the number of crates needing to opt-out of lld due to this bfd / lld difference. For example, all the people using [linkme](https://github.com/dtolnay/linkme), which [doesn't work with lld](dtolnay/linkme#63) or on nightly, need to disable lld. More information about all this, and the historical differences, 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 This optimization has [no visible impact](rust-lang#137685 (comment)) on our benchmarks, so we can use it by default and have a safer/more conservative starting point to remove friction during migration. We can them emit an FCW for the cases where lld detects reliance on encapsulation symbols without `-znostart-stop-gc`, and then revert back to lld's default after a while. No one compiling on nightly relies on this difference, obviously, so doing an FCW is not necessary until after lld is used on stable. I've tested that this correctly links on `linkme` examples. I've also quickly tried to crate an rmake test but the setup with encapsulation symbols is annoying to reproduce: a few link section/name attributes is not enough, we also need to collect symbols between the encapsulation symbols, without referencing them in code, for `-znostart-stop-gc` to only impact this... It should of course be doable though, maybe ```@Kobzol``` will look into it if they have time. r? ```@petrochenkov```

…mpiler-errors Rollup of 8 pull requests Successful merges: - rust-lang#136642 (Put the alloc unit tests in a separate alloctests package) - rust-lang#137337 (Add verbatim linker to AIXLinker) - rust-lang#137363 (compiler: factor Windows x86-32 ABI impl into its own file) - rust-lang#137685 (self-contained linker: conservatively default to `-znostart-stop-gc` on x64 linux) - rust-lang#138000 (atomic: clarify that failing conditional RMW operations are not 'writes') - rust-lang#138063 (Improve `-Zunpretty=hir` for parsed attrs) - rust-lang#138137 (setTargetTriple now accepts Triple rather than string) - rust-lang#138173 (Delay bug for negative auto trait rather than ICEing) r? `@ghost` `@rustbot` modify labels: rollup

Rollup of 5 pull requests Successful merges: - rust-lang#136642 (Put the alloc unit tests in a separate alloctests package) - rust-lang#137528 (Windows: Fix error in `fs::rename` on Windows 1607) - rust-lang#137685 (self-contained linker: conservatively default to `-znostart-stop-gc` on x64 linux) - rust-lang#137757 (On long spans, trim the middle of them to make them fit in the terminal width) - rust-lang#138189 (Mention `env` and `option_env` macros in `std::env::var` docs) r? `@ghost` `@rustbot` modify labels: rollup

Rollup merge of rust-lang#137685 - lqd:nostart-stop-gc, r=petrochenkov self-contained linker: conservatively default to `-znostart-stop-gc` on x64 linux To help stabilization, this PR disables an LLD optimization on x64 linux with respect to `--gc-sections` and encapsulation symbols: it will reduce the number of crates needing to opt-out of lld due to this bfd / lld difference. For example, all the people using [linkme](https://github.com/dtolnay/linkme), which [doesn't work with lld](dtolnay/linkme#63) or on nightly, need to disable lld. More information about all this, and the historical differences, 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 This optimization has [no visible impact](rust-lang#137685 (comment)) on our benchmarks, so we can use it by default and have a safer/more conservative starting point to remove friction during migration. We can them emit an FCW for the cases where lld detects reliance on encapsulation symbols without `-znostart-stop-gc`, and then revert back to lld's default after a while. No one compiling on nightly relies on this difference, obviously, so doing an FCW is not necessary until after lld is used on stable. I've tested that this correctly links on `linkme` examples. I've also quickly tried to crate an rmake test but the setup with encapsulation symbols is annoying to reproduce: a few link section/name attributes is not enough, we also need to collect symbols between the encapsulation symbols, without referencing them in code, for `-znostart-stop-gc` to only impact this... It should of course be doable though, maybe ````@Kobzol```` will look into it if they have time. 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](#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](#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](llvm/llvm-project#68071), [2](llvm/llvm-project#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](#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](e5e2316) 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](#112049 (comment)). 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](#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](#137685), which maintains backwards compatibility with BFD. We found that it has [no effect](#112049 (comment)) on compilation performance and binary size in our benchmark suite. With this change, `linkme` works. Since then, #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](rust-lang/cargo#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](NixOS/nixpkgs#312661) with LLD, which seems to have been fixed with NixOS/nixpkgs#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](#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](#39915), [#71515](#71515)). There were [very early attempts](#29974) to use the gold linker by default, but these had to be [reverted](#30913) because of compatibility issues. Support for LLD was implemented back in [2017](#40018), but it has not been made default yet, except for some more niche targets, such as [WASM](#48125), [ARM Cortex](#53648) or [RISC-V](#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](#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](#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](#85961) implemented the `-Zgcc-ld` flag, which was a hacky way of opting into LLD usage. - June 2021, author `@sledgehammervampire,` reviewer `@petrochenkov` - [MCP 510](rust-lang/compiler-team#510) proposed stabilizing the behavior of `-Zgcc-ld` using more granular flags (`-Clink-self-contained=linker -Clinker-flavor=gcc-lld`). - Initially implemented in [#96827](#96827), but `@petrochenkov` [suggested](#96827 (comment)) a slightly different approach. - The PR was split into [#96884](#96884), where it was decided what will be the individual components of `-Clink-self-contained=linker`. - And [#96401](#96401), which implemented the `-Clinker-flavor` part. - The MCP was finally implemented in [#112910](#112910). - [#116514](#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](#97375), [#98212](#98212), [#100126](#100126), [#100552](#100552), [#102836](#102836), [#110807](#110807), [#101988](#101988), [#116515](#116515) - The implementation of linker flavors with LLD was causing a sort of a combinatorial explosion of various options. [#119906](#119906) suggested a different approach for linker flavors (described [here](#119906 (comment))), 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](#119906 (comment)) and [comment 2](#119906 (comment))), which was implemented in [#123656](#123656). - April 2024, author `@lqd,` reviewer `@petrochenkov` - [#124129](#124129) enabled LLD by default on nightly. - April 2024, author `@lqd,` reviewer `@petrochenkov` - [#137685](#137685), [#137926](#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](#96025) (April 2022), [#117684](#117684) (November 2023), [#137044](#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](#71515 (comment)) 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 #138645. r? `@petrochenkov` `@rustbot` label +needs-fcp +T-compiler try-job: aarch64-gnu try-job: i686-gnu-*

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](#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](#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](llvm/llvm-project#68071), [2](llvm/llvm-project#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](#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](e5e2316) 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](#112049 (comment)). 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](#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](#137685), which maintains backwards compatibility with BFD. We found that it has [no effect](#112049 (comment)) on compilation performance and binary size in our benchmark suite. With this change, `linkme` works. Since then, #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](rust-lang/cargo#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](NixOS/nixpkgs#312661) with LLD, which seems to have been fixed with NixOS/nixpkgs#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](#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](#39915), [#71515](#71515)). There were [very early attempts](#29974) to use the gold linker by default, but these had to be [reverted](#30913) because of compatibility issues. Support for LLD was implemented back in [2017](#40018), but it has not been made default yet, except for some more niche targets, such as [WASM](#48125), [ARM Cortex](#53648) or [RISC-V](#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](#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](#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](#85961) implemented the `-Zgcc-ld` flag, which was a hacky way of opting into LLD usage. - June 2021, author `@sledgehammervampire,` reviewer `@petrochenkov` - [MCP 510](rust-lang/compiler-team#510) proposed stabilizing the behavior of `-Zgcc-ld` using more granular flags (`-Clink-self-contained=linker -Clinker-flavor=gcc-lld`). - Initially implemented in [#96827](#96827), but `@petrochenkov` [suggested](#96827 (comment)) a slightly different approach. - The PR was split into [#96884](#96884), where it was decided what will be the individual components of `-Clink-self-contained=linker`. - And [#96401](#96401), which implemented the `-Clinker-flavor` part. - The MCP was finally implemented in [#112910](#112910). - [#116514](#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](#97375), [#98212](#98212), [#100126](#100126), [#100552](#100552), [#102836](#102836), [#110807](#110807), [#101988](#101988), [#116515](#116515) - The implementation of linker flavors with LLD was causing a sort of a combinatorial explosion of various options. [#119906](#119906) suggested a different approach for linker flavors (described [here](#119906 (comment))), 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](#119906 (comment)) and [comment 2](#119906 (comment))), which was implemented in [#123656](#123656). - April 2024, author `@lqd,` reviewer `@petrochenkov` - [#124129](#124129) enabled LLD by default on nightly. - April 2024, author `@lqd,` reviewer `@petrochenkov` - [#137685](#137685), [#137926](#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](#96025) (April 2022), [#117684](#117684) (November 2023), [#137044](#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](#71515 (comment)) 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 #138645. r? `@petrochenkov` `@rustbot` label +needs-fcp +T-compiler

rustbot assigned petrochenkov Feb 26, 2025

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. labels Feb 26, 2025

This comment has been minimized.

Sign in to view

rustbot added the S-waiting-on-perf Status: Waiting on a perf run to be completed. label Feb 26, 2025

This comment has been minimized.

Sign in to view

rustbot removed the S-waiting-on-perf Status: Waiting on a perf run to be completed. label Feb 26, 2025

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Feb 27, 2025

matthiaskrgr mentioned this pull request Mar 2, 2025

Rollup of 10 pull requests #137877

Closed

tgross35 mentioned this pull request Mar 2, 2025

Rollup of 10 pull requests #137879

Closed

matthiaskrgr mentioned this pull request Mar 3, 2025

Rollup of 10 pull requests #137918

Closed

Kobzol mentioned this pull request Mar 3, 2025

Add a test for -znostart-stop-gc usage with LLD #137926

Merged

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Mar 5, 2025

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 5, 2025

jieyouxu mentioned this pull request Mar 5, 2025

Rollup of 29 pull requests #138071

Closed

jieyouxu mentioned this pull request Mar 5, 2025

Rollup of 15 pull requests #138072

Closed

compiler-errors mentioned this pull request Mar 7, 2025

Rollup of 8 pull requests #138185

Closed

jhpratt mentioned this pull request Mar 8, 2025

Rollup of 5 pull requests #138208

Merged

bors merged commit dfae8e8 into rust-lang:master Mar 8, 2025
7 checks passed

rustbot added this to the 1.87.0 milestone Mar 8, 2025

lqd deleted the nostart-stop-gc branch March 8, 2025 15:38

This was referenced Mar 9, 2025

Some linker sections are missing when building project with nightly toolchain #130397

Closed

Rust Compatibility Issues Eliah-Lakhin/ad-astra#7

Open

smoelius mentioned this pull request Mar 10, 2025

Eliminate use of gold linker rust-fuzz/afl.rs#597

Merged

scootermon mentioned this pull request Mar 11, 2025

Zigbuild linking fails with nightly (2025-03-09) on x64 linux rust-cross/cargo-zigbuild#327

Closed

This was referenced Mar 11, 2025

Linking with ld.gold fails: "nostart-stop-gc: unknown -z option" rust-fuzz/honggfuzz-rs#97

Closed

Restore use of lld in CI dtolnay/linkme#112

Merged

lqd mentioned this pull request Apr 30, 2025

Use lld by default on x86_64-unknown-linux-gnu stable #140525

Merged

torokati44 mentioned this pull request May 22, 2025

ci: Remove lld workaround for linkme ruffle-rs/ruffle#20460

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

self-contained linker: conservatively default to `-znostart-stop-gc` on x64 linux #137685

self-contained linker: conservatively default to `-znostart-stop-gc` on x64 linux #137685

Uh oh!

lqd commented Feb 26, 2025 •

edited

Loading

Uh oh!

lqd commented Feb 26, 2025 •

edited

Loading

Uh oh!

This comment has been minimized.

bors commented Feb 26, 2025

Uh oh!

bors commented Feb 26, 2025

Uh oh!

This comment has been minimized.

rust-timer commented Feb 26, 2025

Uh oh!

mati865 commented Feb 27, 2025

Uh oh!

Kobzol commented Feb 27, 2025

Uh oh!

lqd commented Feb 27, 2025 •

edited

Loading

Uh oh!

petrochenkov commented Feb 27, 2025

Uh oh!

bors commented Feb 27, 2025

Uh oh!

bors commented Feb 27, 2025

Uh oh!

compiler-errors commented Mar 1, 2025

Uh oh!

petrochenkov commented Mar 5, 2025

Uh oh!

bors commented Mar 5, 2025

Uh oh!

Uh oh!

Uh oh!

self-contained linker: conservatively default to -znostart-stop-gc on x64 linux #137685

self-contained linker: conservatively default to -znostart-stop-gc on x64 linux #137685

Uh oh!

Conversation

lqd commented Feb 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lqd commented Feb 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

bors commented Feb 26, 2025

Uh oh!

bors commented Feb 26, 2025

Uh oh!

This comment has been minimized.

rust-timer commented Feb 26, 2025

Overall result: no relevant changes - no action needed

Instruction count

Max RSS (memory usage)

Cycles

Binary size

Uh oh!

mati865 commented Feb 27, 2025

Uh oh!

Kobzol commented Feb 27, 2025

Uh oh!

lqd commented Feb 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

petrochenkov commented Feb 27, 2025

Uh oh!

bors commented Feb 27, 2025

Uh oh!

bors commented Feb 27, 2025

Uh oh!

compiler-errors commented Mar 1, 2025

Uh oh!

petrochenkov commented Mar 5, 2025

Uh oh!

bors commented Mar 5, 2025

Uh oh!

Uh oh!

Uh oh!

self-contained linker: conservatively default to `-znostart-stop-gc` on x64 linux #137685

self-contained linker: conservatively default to `-znostart-stop-gc` on x64 linux #137685

lqd commented Feb 26, 2025 •

edited

Loading

lqd commented Feb 26, 2025 •

edited

Loading

lqd commented Feb 27, 2025 •

edited

Loading