Add different entry points for x.py

[jyn514]

Proposal

Summary

As shown by rust-lang/rust#78466, https://internals.rust-lang.org/t/experience-report-contributing-to-rust-lang-rust/12012, and rust-lang/rust#59864 (comment) have shown, people are still having trouble with bootstrapping even after the changes to defaults and the new explanations in the bootstrapping chapter of the dev-guide. Part of the issue is that x.py's job is inherently complicated, and that most of the commands are ambiguous once you take stages into account. It would be great to have smaller commands that are focused on specific groups of contributors, so you can choose the build steps unambiguously and give helpful errors when they don't make sense.

Proposed Solution

Have an x.py in many different directories that has settings for that directory. For example, library/library.py build would be the same as x.py build library/test --stage 0 today, and library/library.py doc would be the same as x.py doc --stage 0 library/std today. For other more complicated tools, the defaults would be different: src/tools/rustdoc/rustdoc.py doc would be the same as x.py doc --stage 1, compiler/compiler.py build would be the same as x.py build --stage 1 library/std.

These are the entrypoints I propose:

.
├── compiler
│   ├── rustc
│   └── compiler.py
├── library
│   ├── std
│   └── library.py
├── Makefile
├── src
│   └── tools
│       └── rustdoc
│           └── rustdoc.py
└── x.py

The top-level x.py would still be the same as it is today.

I plan to start with library.py and if that goes well, add the other entrypoints. For library/ especially, I think this would be a low-maintenance, high-impact way to greatly simplify the build process.

Eventually, if this goes well, x.py could be soft-deprecated in the documentation to suggest the other entrypoints.

Mentors or Reviewers

@Mark-Simulacrum

Process

The main points of the Major Change Process is as follows:

• File an issue describing the proposal.
• A compiler team member or contributor who is knowledgeable in the area can second by writing @rustbot second.
  • Finding a "second" suffices for internal changes. If however you are proposing a new public-facing feature, such as a -C flag, then full team check-off is required.
  • Compiler team members can initiate a check-off via @rfcbot fcp merge on either the MCP or the PR.
• Once an MCP is seconded, the Final Comment Period begins. If no objections are raised after 10 days, the MCP is considered approved.

You can read more about Major Change Proposals on forge.

Comments

This issue is not meant to be used for technical discussion. There is a Zulip stream for that. Use this issue to leave procedural comments, such as volunteering to review, indicating that you second the proposal (or third, etc), or raising a concern that you would like to be addressed.

[rustbot]

This issue is not meant to be used for technical discussion. There is a Zulip stream for that. Use this issue to leave procedural comments, such as volunteering to review, indicating that you second the proposal (or third, etc), or raising a concern that you would like to be addressed.

cc @rust-lang/compiler @rust-lang/compiler-contributors

[jyn514]

I'm closing this, I no longer think it's a good idea:

• It adds more maintenance burden to x.py
• It's not very discoverable, and it makes it more confusing how x.py behaves in any given situation, especially for new people who are still getting used to "wait, I can't use cargo?" New contributors are the primary audience for this, so if it doesn't help them it doesn't seem very useful.

[jyn514]

I do think we could make some improvement in this area, but I'm not sure what it is.

[pnkfelix]

Something that came up in discussion of this: I wouldn't be opposed to having per-directory shell scripts that demonstrate the single most common invocation to x.py for handling the content of that directory.

(We would probably want to test the scripts in some fashion, though. Even just making sure that they run without hitting errors on some target would probably suffice...)