Add recommendations for distro usage

[workingjubilee]

While talking to Gentoo's people about possible issues that might be affecting how Gentoo's rustc is compiling things, it came up that we, The Rust Project™, don't really document what are basically the "minimum viable build settings" for important components of rustc, such as LLVM, or anything else we would appreciate. We do, of course, have the dist profile via bootstrap.dist.toml which encodes many of those, but there's more than just that.

For instance, bootstrap sets LLVM_UNREACHABLE_OPTIMIZE="OFF" for the CMake build, but we also support usage of a system or external LLVM. That system LLVM support came first, and we don't want to break it, but we also would really like all LLVMs that are used with rustc to have the same setting, which means we have to coordinate this setting across LLVMs that aren't built via bootstrap. This coordination might be optimistic but the benefit of stopping execution immediately, even if it's only on a gradually-decreasing percent of LLVM-related bugs, is huge, as it means we're only a few line-tables away from getting a function name that is the culprit and don't have a mysterious miscompilation instead. The mysterious miscompilations that can't be stopped by simple means are quite enough work for us to handle.

We could of course just expect folks to stare into random segments of bootstrap's Rust code and duplicate the build configurations we have buried in there but... that seems like a bit of a non-starter.

Anyways, the idea here is to try to document at least a few of these things. The big one to document our expectations on for LLVM is https://rustc-dev-guide.rust-lang.org/backend/updating-llvm.html since that is apparently often referenced by distros, or at least Gentoo, for answers about things that need such work, like LLVM compatibility.

I can open a PR addressing the first rec but I'm wondering now if we should have more of a full-on page for this, or something like that.

[workingjubilee]

Oh, one particular thing that I have been pondering is how to improve the issue reports we get from distros and where that should be addressed. That might be better off embedded somehow in our new issue templates, though (for example).

[eli-schwartz]

My recommendation in this discussion was that you can get a lot of really great information about how the user has built rust and llvm on Gentoo, by asking for:

emerge --info "dev-lang/rust:1.95.0"
emerge --info "llvm-core/llvm:22"

(tweak for major version of llvm and full version of rust -- this is slot syntax for co-installable versions of a package, and every rustc version can be parallel installed but only major llvm versions)

including stuff like what unconventional CXXFLAGS the user has built it with. (In particular take a look at the "Package Settings" section which may differ from the global defaults.)

[workingjubilee]

Two other details that come up, one based on reviewing the issue that inspired the conversation which lead to, itself, this issue, and another from Gentoo's commentary on building/testing Rust code at https://wiki.gentoo.org/wiki/Project:Rust/rust-dev

1. We can ask nicely for frame pointers to be used in building rustc and LLVM and recommend that nonleaf pointers are used, with the relevant commands to pass through CXXFLAGS (-fno-omit-frame-pointer -momit-leaf-frame-pointer) and RUSTFLAGS (-Cforce-frame-pointers=non-leaf). We should be clear this is not the same as the LLVM_UNREACHABLE_OPTIMIZE configuration ask, as it is not a soundness requirement on most platforms (though it can be, e.g. without it, unwinding doesn't work too well on aarch64-unknown-linux-gnu), it is simply for debuggability of the compiler.
2. We can document some of "the little things" that make building significant amounts of Rust manageable, which our build systems do implicitly, like using --cap-lints=allow (especially useful for the packaging of dependencies of rustc, since we literally cannot start emitting errors for them without ceasing to being able to build rustc!)