From cb8bd83888cddc37c912be648ce5a814b08ceb25 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Tue, 5 Aug 2014 19:51:02 -0700 Subject: [PATCH] rustdoc: Run all work in a separate task 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 #13259 cc #16275 cc rust-lang/cargo#302 --- src/librustdoc/lib.rs | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs index ddd06e427d7df..fb974403858a0 100644 --- a/src/librustdoc/lib.rs +++ b/src/librustdoc/lib.rs @@ -89,7 +89,40 @@ local_data_key!(pub analysiskey: core::CrateAnalysis) type Output = (clean::Crate, Vec ); 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 {