Skip to content

Commit

Permalink
rustdoc: Run all work in a separate task
Browse files Browse the repository at this point in the history
There's a good long comment explaining why. The tl;dr; is that I have no idea
why this is necessary, but it gets --test to work on windows which is something,
right?

cc rust-lang#13259
cc rust-lang#16275
cc rust-lang/cargo#302
  • Loading branch information
alexcrichton committed Aug 6, 2014
1 parent f5ac411 commit cb8bd83
Showing 1 changed file with 34 additions and 1 deletion.
35 changes: 34 additions & 1 deletion src/librustdoc/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,40 @@ local_data_key!(pub analysiskey: core::CrateAnalysis)
type Output = (clean::Crate, Vec<plugins::PluginJson> );

pub fn main() {
std::os::set_exit_status(main_args(std::os::args().as_slice()));
// Why run rustdoc in a separate task? That's a good question!
//
// We first begin our adventure at the ancient commit of e7c4fb69. In this
// commit it was discovered that the stack limit frobbing on windows ended
// up causing some syscalls to fail. This was worked around manually in the
// relevant location.
//
// Our journey now continues with #13259 where it was discovered that this
// stack limit frobbing has the ability to affect nearly any syscall. Note
// that the key idea here is that there is currently no knowledge as to why
// this is happening or how to preserve it, fun times!
//
// Now we continue along to #16275 where it was discovered that --test on
// windows didn't work at all! Yet curiously rustdoc worked without --test.
// The exact reason that #16275 cropped up is that during the expansion
// phase the compiler attempted to open libstd to read out its macros. This
// invoked the LLVMRustOpenArchive shim which in turned went to LLVM to go
// open a file and read it. Lo and behold this function returned an error!
// It was then discovered that when the same fix mentioned in #13259 was
// applied, the error went away. The plot thickens!
//
// Remember that rustdoc works without --test, which raises the question of
// how because the --test and non --test paths are almost identical. The
// first thing both paths do is parse and expand a crate! It turns out that
// the difference is that --test runs on the *main task* while the normal
// path runs in subtask. It turns out that running --test in a sub task also
// fixes the problem!
//
// So, in summary, it is unknown why this is necessary, what it is
// preventing, or what the actual bug is. In the meantime, this allows
// --test to work on windows, which seems good, right? Fun times.
spawn(proc() {
std::os::set_exit_status(main_args(std::os::args().as_slice()));
});
}

pub fn opts() -> Vec<getopts::OptGroup> {
Expand Down

1 comment on commit cb8bd83

@alexcrichton
Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

r=sfackler

Please sign in to comment.