Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

rustbuild: neither ./x.py doc --stage 0 nor ./x.py doc --stage 1 --keep-stage 0 regenerate api docs if only rustdoc changed #42686

Closed
QuietMisdreavus opened this issue Jun 15, 2017 · 3 comments
Labels
C-bug Category: This is a bug. T-bootstrap Relevant to the bootstrap subteam: Rust's build system (x.py and src/bootstrap) T-infra Relevant to the infrastructure team, which will review and decide on the PR/issue.

Comments

@QuietMisdreavus
Copy link
Member

If i want to test a change to rustdoc by re-rendering the std docs, i could combine the "rebuild rustdoc" and "render api docs" steps into an ./x.py doc command. If i wanted to avoid rebuilding all of stage1, then i could try ./x.py doc --stage 0, but that doesn't actually re-render the documentation! It gets to that step, sees that the documentation output is newer than the source files for libstd, then skips it. (The same problem occurs with ./x.py doc --stage 1 --keep-stage 0, on a related note.) This requires a rustdoc contributor to rebuild an entire stage to be able to test their change on a rendering of std. (Testing it by rendering a separate crate is still possible, i suppose, but also requires the additional step of linking the toolchain in rustup or using the test rustdoc/rustc by a different means.)

@QuietMisdreavus QuietMisdreavus added the T-bootstrap Relevant to the bootstrap subteam: Rust's build system (x.py and src/bootstrap) label Jun 15, 2017
@QuietMisdreavus
Copy link
Member Author

This is kinda related to #38318, but not precisely. I'd made a comment in there explaining my findings when i first saw this behavior. However, looking back at that issue, that seems to be more about how --keep-stage isn't enabled by default, rather than not considering generated docs to need regeneration after a rustdoc change.

@QuietMisdreavus QuietMisdreavus added the T-infra Relevant to the infrastructure team, which will review and decide on the PR/issue. label Jun 21, 2017
bors added a commit that referenced this issue Jul 27, 2017
Compile rustdoc on-demand

Fixes #43284, fixes #38318, and fixes #39505.

Doesn't directly help with #42686, since we need to rebuild just as much. In fact, this hurts it, since `./x.py doc --stage 0` will now fail. I'm not sure if it did before, but with these changes it runs into the problem where we attempt to use artifacts from bootstrap rustc with a non-bootstrap rustdoc, running into version conflicts. I believe this is solvable, but leaving for a future PR.

This means that rustdoc will no longer be compiled when compiling rustc, by default. However, it is still built from `./x.py build` (for hosts, but not targets, since we don't produce compiler toolchains for them) and will be built for doc tests and crate tests.

After this, the recommended workflow if you want a rustdoc is: `./x.py build --stage 1 src/tools/rustdoc` which will give you a working rustdoc in `build/triple/stage1/bin/rustdoc`. Note that you can add `src/libstd` onto the command to compile libstd as well so that the rustdoc can easily compile crates in the wild. `./x.py doc --stage 1 src/libstd` will document `libstd` with a freshly built rustdoc (if necessary), and will not rebuild rustc on modifications to rustdoc.

r? @alexcrichton
@Mark-Simulacrum Mark-Simulacrum added the C-bug Category: This is a bug. label Jul 27, 2017
@Mark-Simulacrum Mark-Simulacrum added this to the impl period milestone Sep 15, 2017
@aturon aturon removed this from the impl period milestone Sep 15, 2017
@jyn514
Copy link
Member

jyn514 commented Jun 27, 2022

I don't think this is still an issue, I remember using x doc --stage 1 library/std with success (and I think @GuillaumeGomez uses x doc std pretty regularly).

@jyn514 jyn514 closed this as completed Jun 27, 2022
@GuillaumeGomez
Copy link
Member

I confirm it works as expected.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C-bug Category: This is a bug. T-bootstrap Relevant to the bootstrap subteam: Rust's build system (x.py and src/bootstrap) T-infra Relevant to the infrastructure team, which will review and decide on the PR/issue.
Projects
None yet
Development

No branches or pull requests

5 participants