Clean up how doc tests are treated.

Author: ehuss

src/cargo/core/compiler/build_config.rs

@@ -183,16 +183,19 @@ impl CompileMode {
         }
     }
 
-    /// Returns `true` if this is a doc or doc test. Be careful using this.
-    /// Although both run rustdoc, the dependencies for those two modes are
-    /// very different.
+    /// Returns `true` if this is generating documentation.
     pub fn is_doc(self) -> bool {
         match self {
-            CompileMode::Doc { .. } | CompileMode::Doctest => true,
+            CompileMode::Doc { .. } => true,
             _ => false,
         }
     }
 
+    /// Returns `true` if this a doc test.
+    pub fn is_doc_test(self) -> bool {
+        self == CompileMode::Doctest
+    }
+
     /// Returns `true` if this is any type of test (test, benchmark, doc test, or
     /// check test).
     pub fn is_any_test(self) -> bool {

src/cargo/core/compiler/context/compilation_files.rs

@@ -146,6 +146,8 @@ impl<'a, 'cfg: 'a> CompilationFiles<'a, 'cfg> {
     pub fn out_dir(&self, unit: &Unit<'a>) -> PathBuf {
         if unit.mode.is_doc() {
             self.layout(unit.kind).root().parent().unwrap().join("doc")
+        } else if unit.mode.is_doc_test() {
+            panic!("doc tests do not have an out dir");
         } else if unit.target.is_custom_build() {
             self.build_script_dir(unit)
         } else if unit.target.is_example() {
@@ -293,14 +295,12 @@ impl<'a, 'cfg: 'a> CompilationFiles<'a, 'cfg> {
         unit: &Unit<'a>,
         bcx: &BuildContext<'a, 'cfg>,
     ) -> CargoResult<Arc<Vec<OutputFile>>> {
-        let out_dir = self.out_dir(unit);
-
         let ret = match unit.mode {
             CompileMode::Check { .. } => {
                 // This may be confusing. rustc outputs a file named `lib*.rmeta`
                 // for both libraries and binaries.
                 let file_stem = self.file_stem(unit);
-                let path = out_dir.join(format!("lib{}.rmeta", file_stem));
+                let path = self.out_dir(unit).join(format!("lib{}.rmeta", file_stem));
                 vec![OutputFile {
                     path,
                     hardlink: None,
@@ -309,7 +309,10 @@ impl<'a, 'cfg: 'a> CompilationFiles<'a, 'cfg> {
                 }]
             }
             CompileMode::Doc { .. } => {
-                let path = out_dir.join(unit.target.crate_name()).join("index.html");
+                let path = self
+                    .out_dir(unit)
+                    .join(unit.target.crate_name())
+                    .join("index.html");
                 vec![OutputFile {
                     path,
                     hardlink: None,
@@ -329,7 +332,7 @@ impl<'a, 'cfg: 'a> CompilationFiles<'a, 'cfg> {
                 vec![]
             }
             CompileMode::Test | CompileMode::Build | CompileMode::Bench => {
-                self.calc_outputs_rustc(unit, bcx, &out_dir)?
+                self.calc_outputs_rustc(unit, bcx)?
             }
         };
         info!("Target filenames: {:?}", ret);
@@ -341,11 +344,11 @@ impl<'a, 'cfg: 'a> CompilationFiles<'a, 'cfg> {
         &self,
         unit: &Unit<'a>,
         bcx: &BuildContext<'a, 'cfg>,
-        out_dir: &Path,
     ) -> CargoResult<Vec<OutputFile>> {
         let mut ret = Vec::new();
         let mut unsupported = Vec::new();
 
+        let out_dir = self.out_dir(unit);
         let link_stem = self.link_stem(unit);
         let info = if unit.kind == Kind::Host {
             &bcx.host_info
@@ -468,6 +471,10 @@ fn compute_metadata<'a, 'cfg>(
     cx: &Context<'a, 'cfg>,
     metas: &mut HashMap<Unit<'a>, Option<Metadata>>,
 ) -> Option<Metadata> {
+    if unit.mode.is_doc_test() {
+        // Doc tests do not have metadata.
+        return None;
+    }
     // No metadata for dylibs because of a couple issues:
     // - macOS encodes the dylib name in the executable,
     // - Windows rustc multiple files of which we can't easily link all of them.

src/cargo/core/compiler/context/mod.rs

@@ -166,7 +166,7 @@ impl<'a, 'cfg> Context<'a, 'cfg> {
                 }
             }
 
-            if unit.mode == CompileMode::Doctest {
+            if unit.mode.is_doc_test() {
                 // Note that we can *only* doc-test rlib outputs here. A
                 // staticlib output cannot be linked by the compiler (it just
                 // doesn't do that). A dylib output, however, can be linked by

src/cargo/core/compiler/context/unit_dependencies.rs

@@ -129,7 +129,7 @@ fn compute_deps<'a, 'cfg, 'tmp>(
 ) -> CargoResult<Vec<(Unit<'a>, UnitFor)>> {
     if unit.mode.is_run_custom_build() {
         return compute_deps_custom_build(unit, state.cx.bcx);
-    } else if unit.mode.is_doc() && !unit.mode.is_any_test() {
+    } else if unit.mode.is_doc() {
         // Note: this does not include doc test.
         return compute_deps_doc(unit, state);
     }

src/cargo/core/compiler/fingerprint.rs

@@ -1015,6 +1015,8 @@ fn calculate<'a, 'cfg>(
     }
     let mut fingerprint = if unit.mode.is_run_custom_build() {
         calculate_run_custom_build(cx, unit)?
+    } else if unit.mode.is_doc_test() {
+        panic!("doc tests do not fingerprint");
     } else {
         calculate_normal(cx, unit)?
     };
@@ -1339,7 +1341,8 @@ fn write_fingerprint(loc: &Path, fingerprint: &Fingerprint) -> CargoResult<()> {
 pub fn prepare_init<'a, 'cfg>(cx: &mut Context<'a, 'cfg>, unit: &Unit<'a>) -> CargoResult<()> {
     let new1 = cx.files().fingerprint_dir(unit);
 
-    if fs::metadata(&new1).is_err() {
+    // Doc tests have no output, thus no fingerprint.
+    if !new1.exists() && !unit.mode.is_doc_test() {
         fs::create_dir(&new1)?;
     }
 

src/cargo/core/compiler/job_queue.rs

@@ -596,11 +596,10 @@ impl<'a, 'cfg> JobQueue<'a, 'cfg> {
             // being a compiled package.
             Dirty => {
                 if unit.mode.is_doc() {
+                    self.documented.insert(unit.pkg.package_id());
+                    config.shell().status("Documenting", unit.pkg)?;
+                } else if unit.mode.is_doc_test() {
                     // Skip doc test.
-                    if !unit.mode.is_any_test() {
-                        self.documented.insert(unit.pkg.package_id());
-                        config.shell().status("Documenting", unit.pkg)?;
-                    }
                 } else {
                     self.compiled.insert(unit.pkg.package_id());
                     if unit.mode.is_check() {
@@ -613,8 +612,7 @@ impl<'a, 'cfg> JobQueue<'a, 'cfg> {
             Fresh => {
                 // If doc test are last, only print "Fresh" if nothing has been printed.
                 if self.counts[&unit.pkg.package_id()] == 0
-                    && !(unit.mode == CompileMode::Doctest
-                        && self.compiled.contains(&unit.pkg.package_id()))
+                    && !(unit.mode.is_doc_test() && self.compiled.contains(&unit.pkg.package_id()))
                 {
                     self.compiled.insert(unit.pkg.package_id());
                     config.shell().verbose(|c| c.status("Fresh", unit.pkg))?;

src/cargo/core/compiler/mod.rs

@@ -125,7 +125,7 @@ fn compile<'a, 'cfg: 'a>(
 
     let job = if unit.mode.is_run_custom_build() {
         custom_build::prepare(cx, unit)?
-    } else if unit.mode == CompileMode::Doctest {
+    } else if unit.mode.is_doc_test() {
         // We run these targets later, so this is just a no-op for now.
         Job::new(Work::noop(), Freshness::Fresh)
     } else if build_plan {

src/cargo/ops/cargo_clean.rs

@@ -104,6 +104,13 @@ pub fn clean(ws: &Workspace<'_>, opts: &CleanOptions<'_>) -> CargoResult<()> {
     cx.prepare_units(None, &units)?;
 
     for unit in units.iter() {
+        if unit.mode.is_doc() || unit.mode.is_doc_test() {
+            // Cleaning individual rustdoc crates is currently not supported.
+            // For example, the search index would need to be rebuilt to fully
+            // remove it (otherwise you're left with lots of broken links).
+            // Doc tests produce no output.
+            continue;
+        }
         rm_rf(&cx.files().fingerprint_dir(unit), config)?;
         if unit.target.is_custom_build() {
             if unit.mode.is_run_custom_build() {

src/cargo/ops/cargo_compile.rs

@@ -383,7 +383,7 @@ pub fn compile_ws<'a>(
     }
     if let Some(args) = local_rustdoc_args {
         for unit in &units {
-            if unit.mode.is_doc() {
+            if unit.mode.is_doc() || unit.mode.is_doc_test() {
                 bcx.extra_compiler_args.insert(*unit, args.clone());
             }
         }
@@ -701,7 +701,7 @@ fn generate_targets<'a>(
                     filter_targets(packages, Target::is_lib, false, bcx.build_config.mode)
                 {
                     let Proposal { target, pkg, .. } = proposal;
-                    if bcx.build_config.mode == CompileMode::Doctest && !target.doctestable() {
+                    if bcx.build_config.mode.is_doc_test() && !target.doctestable() {
                         ws.config().shell().warn(format!(
                             "doc tests are not supported for crate type(s) `{}` in package `{}`",
                             target.rustc_crate_types().join(", "),