rust-lang / rust-lang/std-dev-guide

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

Open
#30 4 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Shell
Stars
90
Forks
47
Avg merge
9h 22m
Merged PRs (30d)
1

Description

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: https://github.com/rust-lang/std-dev-guide/issues/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.)

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the std-dev-guide opening page and compare its links with the rustc-dev-guide sections on building and testing the compiler. Check the Rust repository README and the rustc book's Getting Started section for existing standard-library guidance. Done means contributors can find concise instructions for x.py build, test, and doc commands for library/std, core, and alloc without searching unrelated compiler chapters.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.