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> {