rustbuild: neither ./x.py doc --stage 0 nor ./x.py doc --stage 1 --keep-stage 0 regenerate api docs if only rustdoc changed
#42686
Labels
Comments
|
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 |
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
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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 doccommand. 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.)The text was updated successfully, but these errors were encountered: