Rollup merge of rust-lang#159765 - Kobzol:bootstrap-docs-json-rebuild, r=Mark-Simulacrum

Avoid spurious rebuilds of JSON docs in bootstrap

Found this while working on rust-lang#159671.

Before, repeated runs of e.g. `x dist rust-docs-json` always rebuilt the docs. It was caused by Cargo not knowing that the output should be JSON, so it was trying to find the HTML files.

Instead of passing the output format through `RUSTDOCFLAGS`, which Cargo doesn't inspect, we now pass it to Cargo directly, which fixes the issue.

Author: jhpratt

src/bootstrap/src/core/build_steps/doc.rs

@@ -721,7 +721,7 @@ impl Step for Std {
             DocumentationFormat::Html => {
                 vec!["--markdown-css", "rust.css", "--markdown-no-toc", "--index-page", &index_page]
             }
-            DocumentationFormat::Json => vec!["--output-format", "json"],
+            DocumentationFormat::Json => vec![],
         };
 
         if !builder.config.docs_minification {
@@ -730,7 +730,47 @@ impl Step for Std {
         // For `--index-page` and `--output-format=json`.
         extra_args.push("-Zunstable-options");
 
-        doc_std(builder, self.format, self.build_compiler, target, &out, &extra_args, &crates);
+        let target_doc_dir_name =
+            if self.format == DocumentationFormat::Json { "json-doc" } else { "doc" };
+        let target_dir = builder
+            .stage_out(self.build_compiler, Mode::Std)
+            .join(target)
+            .join(target_doc_dir_name);
+
+        // This is directory where the compiler will place the output of the command.
+        // We will then copy the files from this directory into the final `out` directory, the specified
+        // as a function parameter.
+        let out_dir = target_dir.join(target).join("doc");
+
+        let mut cargo = doc_std(
+            builder,
+            self.format,
+            self.build_compiler,
+            target,
+            &target_dir,
+            &extra_args,
+            &crates,
+        );
+        match self.format {
+            DocumentationFormat::Html => {}
+            DocumentationFormat::Json => {
+                // We have to pass these directly to cargo, rather than through RUSTDOCFLAGS,
+                // otherwise Cargo will not detect freshness of the output correctly, and keep
+                // rebuilding the docs on every invocation.
+                cargo.args(["-Zunstable-options", "--output-format", "json"]);
+            }
+        }
+
+        let description =
+            format!("library{} in {} format", crate_description(&crates), self.format.as_str());
+
+        {
+            let _guard =
+                builder.msg(Kind::Doc, description, Mode::Std, self.build_compiler, target);
+
+            cargo.into_cmd().run(builder);
+            builder.cp_link_r(&out_dir, &out);
+        }
 
         // Open if the format is HTML
         if let DocumentationFormat::Html = self.format {
@@ -787,25 +827,16 @@ impl DocumentationFormat {
     }
 }
 
-/// Build the documentation for public standard library crates.
+/// Prepare a Cargo command for building the documentation for public standard library crates.
 fn doc_std(
     builder: &Builder<'_>,
     format: DocumentationFormat,
     build_compiler: Compiler,
     target: TargetSelection,
-    out: &Path,
+    target_dir: &Path,
     extra_args: &[&str],
     requested_crates: &[String],
-) {
-    let target_doc_dir_name = if format == DocumentationFormat::Json { "json-doc" } else { "doc" };
-    let target_dir =
-        builder.stage_out(build_compiler, Mode::Std).join(target).join(target_doc_dir_name);
-
-    // This is directory where the compiler will place the output of the command.
-    // We will then copy the files from this directory into the final `out` directory, the specified
-    // as a function parameter.
-    let out_dir = target_dir.join(target).join("doc");
-
+) -> builder::Cargo {
     let mut cargo = builder::Cargo::new(
         builder,
         build_compiler,
@@ -836,13 +867,7 @@ fn doc_std(
     if format == DocumentationFormat::Json || builder.config.library_docs_private_items {
         cargo.rustdocflag("--document-private-items").rustdocflag("--document-hidden-items");
     }
-
-    let description =
-        format!("library{} in {} format", crate_description(requested_crates), format.as_str());
-    let _guard = builder.msg(Kind::Doc, description, Mode::Std, build_compiler, target);
-
-    cargo.into_cmd().run(builder);
-    builder.cp_link_r(&out_dir, out);
+    cargo
 }
 
 /// Prepare a compiler that will be able to document something for `target` at `stage`.