itsscb/cargo
1
0
Fork 0
mirror of https://github.com/rust-lang/cargo.git synced 2025-09-25 11:14:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add parallel frontend to the build performance guide (#15970)

Browse Source 
This extends the build performance guide in the Cargo book with the
parallel frontend. This is the first mechanism we have in the guide that
is not configured via profiles (unless we want to advertise setting
`rustflags` through profiles?), but rather through `RUSTFLAGS`. Which
means that we have to explain how to do that.

I proposed using footnotes for this, so that we can reuse them also for
other thing (such as explaining how to change a profile). An alternative
would be to have a short paragraph at the beginning of the configuration
subsection where we explain all the possible ways of configuring things,
and then we refer to them.

This is a follow up to #15924

r? @epage
This commit is contained in:
Eric Huss 2025-09-19 23:18:54 +00:00 committed by GitHub
commit 5818dcdfdf
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 22 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
src/doc/src/guide/build-performance.md
View File

@ -63,8 +63,29 @@ This will change the [`dev` profile](../reference/profiles.md#dev) to use the [C
Trade-offs:
- ✅ Faster code generation (`cargo build`)
- ❌ **Requires using nightly Rust and an unstable Cargo feature**
- ❌ **Requires using nightly Rust and an [unstable Cargo feature][codegen-backend-feature]**
- ❌ Worse runtime performance of the generated code
- Speeds up build part of `cargo test`, but might increase its test execution part
- ❌ Only available for [certain targets](https://github.com/rust-lang/rustc_codegen_cranelift?tab=readme-ov-file#platform-support)
- ❌ Might not support all Rust features (e.g. unwinding)
[codegen-backend-feature]: ../reference/unstable.md#codegen-backend
### Enable the experimental parallel frontend
Recommendation: Add to your `.cargo/config.toml`:
```toml
[build]
rustflags = "-Zthreads=8"
```
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.
Trade-offs:
- ✅ Faster build times
- ❌ **Requires using nightly Rust and an [unstable Rust feature][parallel-frontend-issue]**
[parallel-frontend-blog]: https://blog.rust-lang.org/2023/11/09/parallel-rustc/
[parallel-frontend-issue]: https://github.com/rust-lang/rust/issues/113349
[build.rustflags]: ../reference/config.md#buildrustflags