Rollup merge of #125022 - GuillaumeGomez:migrate-rustdoc-scrape-examples-ordering, r=jieyouxu

Migrate rustdoc scrape examples ordering

Part of #121876.

This one adds a lot of utility methods/functions. To prevent having too much changes at once, I didn't make the existing rmake tests use these yet but I'll send a follow-up so they all use it.

r? `@jieyouxu`

Author: GuillaumeGomez

src/tools/run-make-support/src/lib.rs

@@ -54,6 +54,15 @@ pub fn static_lib(name: &str) -> PathBuf {
     tmp_dir().join(static_lib_name(name))
 }
 
+pub fn python_command() -> Command {
+    let python_path = std::env::var("PYTHON").expect("PYTHON environment variable does not exist");
+    Command::new(python_path)
+}
+
+pub fn source_path() -> PathBuf {
+    std::env::var("S").expect("S variable does not exist").into()
+}
+
 /// Construct the static library name based on the platform.
 pub fn static_lib_name(name: &str) -> String {
     // See tools.mk (irrelevant lines omitted):

src/tools/run-make-support/src/rustc.rs

@@ -1,5 +1,5 @@
 use std::env;
-use std::ffi::OsString;
+use std::ffi::{OsStr, OsString};
 use std::io::Write;
 use std::path::Path;
 use std::process::{Command, Output, Stdio};
@@ -176,6 +176,13 @@ impl Rustc {
         self
     }
 
+    /// Specify the crate name.
+    pub fn crate_name<S: AsRef<OsStr>>(&mut self, name: S) -> &mut Self {
+        self.cmd.arg("--crate-name");
+        self.cmd.arg(name.as_ref());
+        self
+    }
+
     /// Get the [`Output`][::std::process::Output] of the finished process.
     #[track_caller]
     pub fn command_output(&mut self) -> ::std::process::Output {

src/tools/run-make-support/src/rustdoc.rs

@@ -1,4 +1,5 @@
 use std::env;
+use std::ffi::OsStr;
 use std::io::Write;
 use std::path::Path;
 use std::process::{Command, Output, Stdio};
@@ -45,6 +46,21 @@ impl Rustdoc {
         Self { cmd, stdin: None }
     }
 
+    /// Specify where an external library is located.
+    pub fn extern_<P: AsRef<Path>>(&mut self, crate_name: &str, path: P) -> &mut Self {
+        assert!(
+            !crate_name.contains(|c: char| c.is_whitespace() || c == '\\' || c == '/'),
+            "crate name cannot contain whitespace or path separators"
+        );
+
+        let path = path.as_ref().to_string_lossy();
+
+        self.cmd.arg("--extern");
+        self.cmd.arg(format!("{crate_name}={path}"));
+
+        self
+    }
+
     /// Specify path to the input file.
     pub fn input<P: AsRef<Path>>(&mut self, path: P) -> &mut Self {
         self.cmd.arg(path.as_ref());
@@ -107,6 +123,20 @@ impl Rustdoc {
         self
     }
 
+    /// Specify the crate type.
+    pub fn crate_type(&mut self, crate_type: &str) -> &mut Self {
+        self.cmd.arg("--crate-type");
+        self.cmd.arg(crate_type);
+        self
+    }
+
+    /// Specify the crate name.
+    pub fn crate_name<S: AsRef<OsStr>>(&mut self, name: S) -> &mut Self {
+        self.cmd.arg("--crate-name");
+        self.cmd.arg(name.as_ref());
+        self
+    }
+
     #[track_caller]
     pub fn run_fail_assert_exit_code(&mut self, code: i32) -> Output {
         let caller_location = std::panic::Location::caller();

src/tools/tidy/src/allowed_run_make_makefiles.txt

@@ -248,7 +248,6 @@ run-make/rustdoc-io-error/Makefile
 run-make/rustdoc-scrape-examples-invalid-expr/Makefile
 run-make/rustdoc-scrape-examples-macros/Makefile
 run-make/rustdoc-scrape-examples-multiple/Makefile
-run-make/rustdoc-scrape-examples-ordering/Makefile
 run-make/rustdoc-scrape-examples-remap/Makefile
 run-make/rustdoc-scrape-examples-test/Makefile
 run-make/rustdoc-scrape-examples-whitespace/Makefile

tests/run-make/rustdoc-scrape-examples-ordering/Makefile

@@ -0,0 +1,55 @@
+use run_make_support::{python_command, rustc, rustdoc, source_path, tmp_dir};
+use std::fs::read_dir;
+use std::path::Path;
+
+fn main() {
+    let lib_dir = tmp_dir();
+    let out_dir = tmp_dir().join("rustdoc");
+    let crate_name = "foobar";
+    let deps = read_dir("examples")
+        .unwrap()
+        .filter_map(|entry| entry.ok().map(|e| e.path()))
+        .filter(|path| path.is_file() && path.extension().is_some_and(|ext| ext == "rs"))
+        .collect::<Vec<_>>();
+
+    rustc().input("src/lib.rs").crate_name(crate_name).crate_type("lib").emit("metadata").run();
+
+    let mut out_deps = Vec::with_capacity(deps.len());
+    for dep in deps {
+        let dep_stem = dep.file_stem().unwrap();
+        let out_example = out_dir.join(format!("{}.calls", dep_stem.to_str().unwrap()));
+        rustdoc()
+            .input(&dep)
+            .crate_name(&dep_stem)
+            .crate_type("bin")
+            .output(&out_dir)
+            .extern_(crate_name, lib_dir.join(format!("lib{crate_name}.rmeta")))
+            .arg("-Zunstable-options")
+            .arg("--scrape-examples-output-path")
+            .arg(&out_example)
+            .arg("--scrape-examples-target-crate")
+            .arg(crate_name)
+            .run();
+        out_deps.push(out_example);
+    }
+
+    let mut rustdoc = rustdoc();
+    rustdoc
+        .input("src/lib.rs")
+        .output(&out_dir)
+        .crate_name(crate_name)
+        .crate_type("lib")
+        .arg("-Zunstable-options");
+    for dep in out_deps {
+        rustdoc.arg("--with-examples").arg(dep);
+    }
+    rustdoc.run();
+
+    python_command()
+        .arg(source_path().join("/src/etc/htmldocck.py"))
+        .arg(out_dir)
+        .arg("src/lib.rs")
+        .status()
+        .unwrap()
+        .success();
+}