I got very confused about the exact steps I needed to do to test out some changes to std
while drafting an idea to resolve an outstanding issue, just to check feasibility before I made too many claims. The issue comes in that the rustc-dev-guide
is what's linked from from rust-lang/Rust, and the opening page mentions here, the std-dev-guide
, which contains a lot of helpful procedural and code style/requirements info, and other neat internals info, but nothing about actually building or testing std
(/core
/alloc
etc).
Unfortunately, you're then left confused, and going back to both the README
of the main Rust
repo, and the rustc-dev-guide
to try and scan for any chapter heading mentioning "std" or "library" or similar, until you finally have to sit down and just read and realize it's in the guide called "building the compiler", and running tests is in "testing the compiler".
Honestly if I was newer to coding or otherwise didn't know how bootstrapping compilers and the distribution thereof worked, I probably would've assumed rustc-dev-guide
was a lost cause altogether. It's an odd situation where the existence of this guide makes the presence of this info in rustc-dev-guide
less obvious, because there's a specific place it "should" be. This is probably especially true for people newer to programming or open source than me who may be concerned that technical talk about building the compiler may go over their heads, but would be comfortable trying to play with std
since that's mostly the type of code they're familiar with.
Note, this is mentioned here: #1 but I thought an explicit issue may be better than a comment on that:
* [ ] How to build/test/document the standard library (`x.py build/test/doc --stage 0 library/std` respectively
I can try drafting a simple PR to either copy over and simplify this info as appropriate, or at least say "for building and testing follow the instructions at (link to building the compiler) and (link to testing the compiler)" when I have time, but for now I thought I'd at least raise the issue.
(Edit: I do see now in the rustc
book there's a listing in the Getting Started
that lists std, core, alloc etc, but it's easy to miss and doesn't change much for this book. x.py
also explicitly asks what you want to do but you're unlikely to get there yourself IMO.)