rust-lang / rust-lang/rustc-dev-guide
Add recommendations for distro usage
Nobody has claimed this yet.
- Dominant language
- HTML
- Stars
- 1.9k
- Forks
- 613
- Avg merge
- 17h 24m
- Merged PRs (30d)
- 39
Description
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.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with rustc-dev-guide/src/backend/updating-llvm.md, then compare the settings in bootstrap.dist.toml and src/bootstrap/src/core/build_steps/llvm.rs, including LLVM_UNREACHABLE_OPTIMIZE. Determine which minimum LLVM and other component settings should be documented for distro and external-LLVM users; done means the expectations are clearly recorded in the guide or a linked page.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- compilers, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 45/100