Skip to content

Commit a405cdf

Browse files
committed
Add alternative linker to the build performance guide
1 parent a390202 commit a405cdf

File tree

1 file changed

+26
-6
lines changed

1 file changed

+26
-6
lines changed

src/doc/src/guide/build-performance.md

Lines changed: 26 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ This will:
3838
- Provide an opt-in for when debugging via [`--profile debugging`](../reference/profiles.md#custom-profiles)
3939

4040
Trade-offs:
41-
- ✅ Faster build times
41+
- ✅ Faster code generation (`cargo build`)
4242
- ✅ Faster link times
4343
- ✅ Smaller disk usage of the `target` directory
4444
- ❌ Requires a full rebuild to have a high-quality debugger experience
@@ -83,9 +83,33 @@ rustflags = "-Zthreads=8"
8383
This [`rustflags`][build.rustflags] will enable the [parallel frontend][parallel-frontend-blog] of the Rust compiler, and tell it to use `n` threads. The value of `n` should be chosen according to the number of cores available on your system, although there are diminishing returns. We recommend using at most `8` threads.
8484

8585
Trade-offs:
86-
- ✅ Faster build times
86+
- ✅ Faster build times (both `cargo check` and `cargo build`)
8787
-**Requires using nightly Rust and an [unstable Rust feature][parallel-frontend-issue]**
8888

89+
[parallel-frontend-blog]: https://blog.rust-lang.org/2023/11/09/parallel-rustc/
90+
[parallel-frontend-issue]: https://github.com/rust-lang/rust/issues/113349
91+
[build.rustflags]: ../reference/config.md#buildrustflags
92+
93+
### Use an alternative linker
94+
95+
Consider: installing and configuring an alternative linker, like [LLD](https://lld.llvm.org/), [mold](https://github.com/rui314/mold) or [wild](https://github.com/davidlattimore/wild). For example, to configure mold on Linux, you can add to your `.cargo/config.toml`:
96+
97+
```toml
98+
[target.'cfg(target_os = "linux")']
99+
# mold, if you have GCC 12+
100+
rustflags = ["-C", "link-arg=-fuse-ld=mold"]
101+
102+
# mold, otherwise
103+
linker = "clang"
104+
rustflags = ["-C", "link-arg=-fuse-ld=/path/to/mold"]
105+
```
106+
107+
While dependencies may be built in parallel, linking all of your dependencies happens at once at the end of your build, which can make linking dominate your build times, especially for incremental rebuilds. Often, the linker Rust uses is already fairly fast and the gains from switching may not be worth it, but it is not always the case. For example, Linux targets besides `x86_64-unknown-linux-gnu` still use the Linux system linker which is quite slow (see [rust#39915](https://github.com/rust-lang/rust/issues/39915) for more details).
108+
109+
Trade-offs:
110+
- ✅ Faster link times
111+
- ❌ Might not support all use-cases, in particular if you depend on C or C++ dependencies
112+
89113
## Reducing built code
90114

91115
### Removing unused dependencies
@@ -103,7 +127,3 @@ it can be easy to miss that a dependency is no longer used and can be removed.
103127
Trade-offs:
104128
- ✅ Faster full build and link times
105129
- ❌ May incorrectly flag dependencies as unused or miss some
106-
107-
[parallel-frontend-blog]: https://blog.rust-lang.org/2023/11/09/parallel-rustc/
108-
[parallel-frontend-issue]: https://github.com/rust-lang/rust/issues/113349
109-
[build.rustflags]: ../reference/config.md#buildrustflags

0 commit comments

Comments
 (0)