Technical info on how to compile/test/set up std missing

[ZoopOTheGoop]

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.)

[dimpolo]

Yes please!
What wanted to know:

git clone https://github.com/rust-lang/rust.git
cd rust
./x.py setup # select "a) library: Contribute to the standard library"
./x.py test library/std

Time it took me to find this info:

two hours 😅

[the8472]

The std-dev guide now has a section "Building and Debugging the library crates" which forwards to the rustc-dev guide.

Is that sufficient?

[dimpolo]

It's definitely an improvement!
I think ideally you would want to have a step-by-step guide for:

• setting up the environment
• making a change to std
• writing a test
• testing it
• opening a PR

[jyn514]

short summary of that first step:

Clone rust, cd in
Run cargo install --path src/tools/x
To set up for library dev run x setup library
Then run x check library/std and x test library/std

would be good to add that to https://std-dev-guide.rust-lang.org/development/building-and-debugging.html; rustc-dev guide doesn't have the instructions for the library profile