about summary refs log tree commit diff
path: root/src/doc
AgeCommit message (Collapse)AuthorLines
2025-07-22Rollup merge of #144251 - tshepang:rdg-sync, r=jieyouxu许杰友 Jieyou Xu (Joe)-8/+8
rustc-dev-guide subtree update Subtree update of `rustc-dev-guide` to https://github.com/rust-lang/rustc-dev-guide/commit/cca233729f03d0c59456cd3e866f92681faf4c54. Created using https://github.com/rust-lang/josh-sync. r? ```@ghost```
2025-07-22Rollup merge of #142097 - ZuseZ4:offload-host1, r=oli-obk许杰友 Jieyou Xu (Joe)-0/+8
gpu offload host code generation r? ghost This will generate most of the host side code to use llvm's offload feature. The first PR will only handle automatic mem-transfers to and from the device. So if a user calls a kernel, we will copy inputs back and forth, but we won't do the actual kernel launch. Before merging, we will use LLVM's Info infrastructure to verify that the memcopies match what openmp offloa generates in C++. `LIBOMPTARGET_INFO=-1 ./my_rust_binary` should print that a memcpy to and later from the device is happening. A follow-up PR will generate the actual device-side kernel which will then do computations on the GPU. A third PR will implement manual host2device and device2host functionality, but the goal is to minimize cases where a user has to overwrite our default handling due to performance issues. I'm trying to get a full MVP out first, so this just recognizes GPU functions based on magic names. The final frontend will obviously move this over to use proper macros, like I'm already doing it for the autodiff work. This work will also be compatible with std::autodiff, so one can differentiate GPU kernels. Tracking: - https://github.com/rust-lang/rust/issues/131513
2025-07-21Merge pull request #2512 from rust-lang/rustc-pullTshepang Mbambo-26/+37
Rustc pull update
2025-07-21fix some typosTshepang Mbambo-6/+6
2025-07-21Merge ref '460259d14de0' from rust-lang/rustThe rustc-josh-sync Cronjob Bot-25/+36
Pull recent changes from https://github.com/rust-lang/rust via Josh. Upstream ref: 460259d14de0274b97b8801e08cb2fe5f16fdac5 Filtered ref: 599ee17eb87c83f97eb37fd9fe264da65d4c9461 This merge was created using https://github.com/rust-lang/josh-sync.
2025-07-21Prepare for merging from rust-lang/rustThe rustc-josh-sync Cronjob Bot-1/+1
This updates the rust-version file to 460259d14de0274b97b8801e08cb2fe5f16fdac5.
2025-07-20Add new `needs-backends` tests annotationsGuillaume Gomez-0/+1
2025-07-20Add new `ignore-backends` tests annotationsGuillaume Gomez-0/+1
2025-07-20Auto merge of #143002 - Enselic:tests-ui-run-fail-exit-vs-signal, r=petrochenkovbors-7/+19
tests: Require `run-fail` ui tests to have an exit code (`SIGABRT` not ok) And introduce two new directives for ui tests: * `run-crash` * `run-fail-or-crash` Normally a `run-fail` ui test like tests that panic shall not be terminated by a signal like `SIGABRT`. So begin having that as a hard requirement. Some of our current tests do terminate by a signal/crash however. Introduce and use `run-crash` for those tests. Note that Windows crashes are not handled by signals but by certain high bits set on the process exit code. Example exit code for crash on Windows: `0xc000001d` (`STATUS_ILLEGAL_INSTRUCTION`). Because of this, we define "crash" on all platforms as "not exit with success and not exit with a regular failure code in the range 1..=127". Some tests behave differently on different targets: * Targets without unwind support will abort (crash) instead of exit with failure code 101 after panicking. As a special case, allow crashes for `run-fail` tests for such targets. * Different sanitizer implementations handle detected memory problems differently. Some abort (crash) the process while others exit with failure code 1. Introduce and use `run-fail-or-crash` for such tests. This adds further (cc https://github.com/rust-lang/rust/pull/142304, https://github.com/rust-lang/rust/pull/142886) protection against the regression in https://github.com/rust-lang/rust/issues/123733 since that bug also manifested as `SIGABRT` in `tests/ui/panics/panic-main.rs` (shown as `Aborted (core dumped)` in the logs attached to that issue, and I have also been able to reproduce this locally). ### TODO - [x] **Q:** what about on Windows? **A:** we'll treat any exit code outside of 1 - 127 as "crashed", and we'll do the same on unix. - [x] test all permutations of actual vs expected **Done:** See https://github.com/rust-lang/rust/pull/143002#issuecomment-3007502894. - [x] Handle targets without unwind support - [x] Add `run-fail-or-crash` for some sanitizer tests - [x] remote-test-client. See https://github.com/rust-lang/rust/pull/143448 ### Zulip discussion See https://rust-lang.zulipchat.com/#narrow/channel/122651-general/topic/compiletest.3A.20terminate.20by.20signal.20vs.20exit.20with.20error/with/525611235 try-job: aarch64-apple try-job: x86_64-msvc-1 try-job: x86_64-gnu try-job: dist-i586-gnu-i586-i686-musl try-job: test-various try-job: armhf-gnu
2025-07-19tests: Require `run-fail` ui tests to have an exit code (`SIGABRT` not ok)Martin Nordholts-7/+19
And introduce two new directives for ui tests: * `run-crash` * `run-fail-or-crash` Normally a `run-fail` ui test like tests that panic shall not be terminated by a signal like `SIGABRT`. So begin having that as a hard requirement. Some of our current tests do terminate by a signal/crash however. Introduce and use `run-crash` for those tests. Note that Windows crashes are not handled by signals but by certain high bits set on the process exit code. Example exit code for crash on Windows: `0xc000001d`. Because of this, we define "crash" on all platforms as "not exit with success and not exit with a regular failure code in the range 1..=127". Some tests behave differently on different targets: * Targets without unwind support will abort (crash) instead of exit with failure code 101 after panicking. As a special case, allow crashes for `run-fail` tests for such targets. * Different sanitizer implementations handle detected memory problems differently. Some abort (crash) the process while others exit with failure code 1. Introduce and use `run-fail-or-crash` for such tests.
2025-07-19Rollup merge of #144149 - reallesee:master, r=Noratrieb许杰友 Jieyou Xu (Joe)-1/+1
docs: update link to RISC-V and Xtensa installation guide Replace outdated link https://docs.esp-rs.org/book/installation/riscv-and-xtensa.html with the official Espressif documentation at https://docs.espressif.com/projects/rust/book/installation/index.html
2025-07-18add unstable-books doc for offloadManuel Drehwald-0/+8
2025-07-18docs: update link to RISC-V and Xtensa installation guideMicke-1/+1
2025-07-18Rollup merge of #143961 - 1c3t3a:correct-exploit-mitigations, r=rcvalleMatthias Krüger-11/+11
Correct which exploit mitigations are enabled by default This was brought up by ``@Noratrieb`` in [#project-exploit-mitigations > Incorrect table in the rustc book](https://rust-lang.zulipchat.com/#narrow/channel/343119-project-exploit-mitigations/topic/Incorrect.20table.20in.20the.20rustc.20book/with/523684203). Thanks! :) [Rendered](https://github.com/rust-lang/rust/blob/132a47e72316b60e99c3e5fefb9c3a06641138e4/src/doc/rustc/src/exploit-mitigations.md) r? ``@rcvalle``
2025-07-18fix typosYiqun Liu-1/+1
2025-07-18Rollup merge of #144049 - tshepang:rust-push, r=jieyouxuMatthias Krüger-983/+151
rustc-dev-guide subtree update r? ghost
2025-07-17parse `const trait Trait`Deadbeef-6/+3
2025-07-17copy-paste convenienceTshepang Mbambo-1/+4
2025-07-17Merge ref 'fd2eb391d032' from rust-lang/rustThe rustc-josh-sync Cronjob Bot-170/+214
Pull recent changes from https://github.com/rust-lang/rust via Josh. Upstream ref: fd2eb391d032181459773f3498c17b198513e0d0 Filtered ref: 1ea8d5f9c22f0930a0caa27637ef9232fead3c2b This merge was created using https://github.com/rust-lang/josh-sync.
2025-07-17Prepare for merging from rust-lang/rustThe rustc-josh-sync Cronjob Bot-1/+1
This updates the rust-version file to fd2eb391d032181459773f3498c17b198513e0d0.
2025-07-17some improvements to "Invariants of the type system"Tshepang Mbambo-19/+22
2025-07-16go over invariants again :3lcnr-33/+48
Co-authored-by: Boxy <rust@boxyuwu.dev>
2025-07-15Add `0323pin` as target maintainer, and fix link to pkgsrc-wip and explain.Havard Eidnes-1/+2
2025-07-15Correct which exploit mitigations are enabled by defaultBastian Kersting-11/+11
2025-07-15Rollup merge of #143938 - rustbot:docs-update, r=ehussSamuel Tardieu-0/+0
Update books ## rust-lang/book 3 commits in ef1ce8f87a8b18feb1b6a9cf9a4939a79bde6795..b2d1a0821e12a676b496d61891b8e3d374a8e832 2025-07-08 17:24:41 UTC to 2025-07-02 21:30:57 UTC - Chapter 16 from tech review (rust-lang/book#4438) - WIP ch 17 edits after tech review (rust-lang/book#4319) - Chapter 15 from tech review (rust-lang/book#4433) ## rust-embedded/book 1 commits in 41f688a598a5022b749e23d37f3c524f6a0b28e1..fe88fbb68391a465680dd91109f0a151a1676f3e 2025-07-08 18:54:25 UTC to 2025-07-08 18:54:25 UTC - Clarify usage of #[interrupt] attribute and recommend device crate re… (rust-embedded/book#386) ## rust-lang/nomicon 3 commits in 8b61acfaea822e9ac926190bc8f15791c33336e8..3ff384320598bbe8d8cfe5cb8f18f78a3a3e6b15 2025-07-05 07:34:22 UTC to 2025-07-05 07:13:51 UTC - Add build script part to FFI chapter for more clear and smooth learn … (rust-lang/nomicon#440) - Cleanups for tree example of splitting borrows (rust-lang/nomicon#443) - Handle drop zst (rust-lang/nomicon#425) ## rust-lang/reference 17 commits in e9fc99f107840813916f62e16b3f6d9556e1f2d8..1f45bd41fa6c17b7c048ed6bfe5f168c4311206a 2025-07-11 23:15:51 UTC to 2025-07-01 16:49:33 UTC - mention an important use for the naked attribute (rust-lang/reference#1929) - Array expression repeat operands can be const blocks. (rust-lang/reference#1928) - Document (tuple) struct pattern namespace behavior (rust-lang/reference#1925) - Replace set of en dashes with set of em dashes (rust-lang/reference#1926) - Update `should_panic` to use the attribute template (rust-lang/reference#1882) - const-eval.const-expr.borrows: mention indirect places (rust-lang/reference#1865) - associated-items.md: remove redundant word (rust-lang/reference#1874) - introduction.md: replace hard-to-read example (rust-lang/reference#1873) - typo (rust-lang/reference#1924) - Update `ignore` to use the attribute template (rust-lang/reference#1881) - Update `test` to use the attribute template (rust-lang/reference#1880) - Update `cfg_attr` to use the attribute template (rust-lang/reference#1879) - Update `cfg` to use the attribute template (rust-lang/reference#1878) - allow constants to refer to mutable/external memory, but reject such constants as patterns (rust-lang/reference#1859) - Remove outdated comment about non-copy unions (rust-lang/reference#1872) - Add a template for documenting attributes (rust-lang/reference#1877) - Switch enum grammar to use "variant" (rust-lang/reference#1876) ## rust-lang/rust-by-example 1 commits in 288b4e4948add43f387cad35adc7b1c54ca6fe12..e386be5f44af711854207c11fdd61bb576270b04 2025-07-04 23:17:15 UTC to 2025-07-04 23:17:15 UTC - Update Chinese translations (rust-lang/rust-by-example#1943)
2025-07-15Merge pull request #2504 from lolbinarycat/lolbinarycat-patch-2许杰友 Jieyou Xu (Joe)-1/+1
2025-07-14Merge pull request #2497 from rust-lang/tshepang-git-cloneManuel Drehwald-6/+6
tweak some git clone commands
2025-07-14Update booksrustbot-0/+0
2025-07-15Remove mentions of `./x suggest` and `suggest-tests` in rustc-dev-guideJieyou Xu-80/+0
2025-07-13Compiletest: Simplify {Html,Json}DocCk directive handlingLeón Orell Valerian Liehr-0/+3
2025-07-11directives.md: build-aux-docs does not work with aux-cratelolbinarycat-1/+1
2025-07-11Rollup merge of #143747 - Gelbpunkt:aarch64-musl-maintainer, r=jieyouxuMatthias Krüger-1/+51
Add target maintainer information for aarch64-unknown-linux-musl Mentioning ``@famfo`` so that they can review the documentation. We're both very invested in this target; I originally promoted it to tier 2 with host tools in rust-lang/rust#76420 back in 2020.
2025-07-11Merge pull request #2502 from Kobzol/rustc-josh-sync-ci许杰友 Jieyou Xu (Joe)-102/+9
2025-07-10Add target maintainer information for aarch64-unknown-linux-muslJens Reidel-1/+51
Signed-off-by: Jens Reidel <adrian@travitia.xyz>
2025-07-10Auto merge of #143525 - Shourya742:2025-07-06-add-profiler, r=Kobzolbors-2/+9
Add profiler to bootstrap command This PR adds command profiling to the bootstrap command. It tracks the total execution time and records cache hits for each command. It also provides the ability to export execution result to a JSON file. Integrating this with Chrome tracing could further enhance observability. r? `@Kobzol`
2025-07-10update rust-dev-guide to point about new command execution summary report ↵bit-aloo-2/+9
under bootstrap profiling section
2025-07-10Migrate rustc-pull to CI workflow from `josh-sync`Jakub Beránek-102/+9
2025-07-10Mention that compiler-builtins is now using `rustc-josh-sync`Jakub Beránek-1/+2
2025-07-10Merge pull request #2499 from rust-lang/tshepang-patch-2nora-1/+3
distcheck has only one possible invocation
2025-07-10Merge pull request #2500 from rust-lang/tshepang-patch-3nora-1/+1
do not invent a name
2025-07-09do not invent a nameTshepang Mbambo-1/+1
Nowhere else is this called "Dist check"
2025-07-09distcheck had only one possible invocationTshepang Mbambo-1/+3
That is, calling it an example is misleading
2025-07-09add missing wordTshepang Mbambo-1/+1
2025-07-09Add a new maintainer to the wasm32-wasip1 targetMarcin Kolny-0/+1
2025-07-09tweak some git clone commandsTshepang Mbambo-6/+6
- --depth=1 is more useful for once-off uses, like on ci - .git postfix on github repo url is not needed
2025-07-09use a consistent (and recommended) invocationTshepang Mbambo-7/+7
./x is recommended over running ./x.py directly, and is the more commonly-used invocation of bootstrap in the guide
2025-07-08Auto merge of #140525 - lqd:stabilize-lld, r=petrochenkovbors-43/+59
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
2025-07-08Rollup merge of #143622 - ↵Matthias Krüger-1/+51
Gelbpunkt:mips64-unknown-linux-muslabi64-target-maintainer, r=jieyouxu Add target maintainer information for mips64-unknown-linux-muslabi64 The `mips64-unknown-linux-muslabi64` target is currently rather broken, but I'm working on getting it fixed so that it can at least be used again. While I can't commit to maintaining the LLVM side of this target, I don't mind looking into any other MIPS or musl-related issues that arise with this target. See e.g. rust-lang/rust#143409 for some rustc fixes I have in the pipeline and https://github.com/rust-lang/libc/pull/4509, https://github.com/rust-lang/libc/pull/4527, https://github.com/rust-lang/libc/pull/4528, https://github.com/rust-lang/libc/pull/4529, https://github.com/rust-lang/libc/pull/4530 for fixing the libc definitions for this target. I'm adding myself as a maintainer mostly due to [this interaction](https://github.com/rust-lang/libc/pull/4530#issuecomment-3045912645). LLVM support has been a concern for these targets in the past, but it shouldn't hurt to have a nominal maintainer for these even if they remain tier 3. From my experience, LLVM for MIPS is working well nowadays unless you decide to use LLD, which is horribly broken on MIPS.
2025-07-08Rollup merge of #143600 - alexcrichton:wasm32-wasip1-doc-reword, r=jieyouxuMatthias Krüger-25/+23
Update intro blurb in `wasm32-wasip1` docs I was reading over this documentation in light of the effort to enlist more maintainers for Tier 2 targets and figured it was time for a refresh of this documentation now that historical renames/etc have all become a thing of the past. No new major changes to this documentation, mostly just wanted to update it and reflect the modern status quo for this target.
2025-07-08document new stable flags, with x64 linux implementation notesRémy Rakic-43/+59