Add parallel frontend to the build performance guide

[Kobzol]

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

[epage]

Should our default recommendation be the CLI or build.rustflags? I lean towards the latter:

• The docs call out the other mechanisms
• Starts the user off with a more permanent place to put this so they don't have to remember on every invocation

[epage]

Granted, this means we need to update the config section to be more nuanced since this wouldn't be set in Cargo.toml

[epage]

build.rustflags was added in addition to the command line. Do we need both?

[Kobzol]

I think that we should show both, as using RUSTLAGS is useful for one-off tests. Not sure if we need to repeat both ways to configure rustflags for all workarounds that use it though. Once/if we have a second mechanism that uses RUSTFLAGS, I'd perhaps move this to the beginning of the section and then just refer to it.

[epage]

If our goal is "show how to speed your build", having our recommendation be something that is not required on every command seems better to me. If we link out to the docs, it will list out how else it can be set (maybe we could even call out that there are other ways). Not a fan of the redundancy though.

[Kobzol]

I figured that for manually benchmarking which one is faster (e.g. using back-to-back CLI invocations or e.g. hyperfine), setting it through the environment variable is easier. For long term usage the config is ofc better.

Also regarding the config, there are trade-offs between setting build.rustflags and target.rustflags 😆 Stuff is complicated.

[epage]

Framing this as "what steps you need to benchmark" vs "what steps to apply to get the benefit" are very different. If we were going for the former, the debug info section should instead use the environment variable for it.

As for which *.rustflags, this is platform agnostic so it seems like that would be build.rustflags.

[Kobzol]

Which rustflags flag is important regarding their priority, and whether they are used for build scripts, but for the parallel frontend that probably won't matter, so let's keep it simple and use build.rustflags, yeah.

[epage]

Should we have this link out to the documentation for the unstable feature? imo it would be good to help people track the progress. I went with the docs to add an extra step in the hope that it reduces "whats the status?" posts.

I was wondering about this for our other one but that seemed to have fallen through the cracks

[Kobzol]

Will add a link to the parallel frontend issue. There is no tracking issue for Cranelift, I think, but we can link to rust-lang/rust#77933.

[Kobzol]

I linked to the unstable Cargo -Zcodegen-backend feature in Cargo reference in the book.

[epage]

Should we somewhere mention the way to make nightly your default?

[Kobzol]

Hmm, that seems a bit orthogonal to this document, and more related to rustup. We also don't describe how to actually install nightly (nor should we). The example should use +nightly though, that's a good point.

[Kobzol]

I think it now looks as you wanted it to, but happy to make further edits :)

[epage]

Since we're looking at a couple more changes, mind cleaning up the commits while you are at it? For me, having them go back and forth in different directions makes it harder to review

[Kobzol]

Ok, done.