From 038a9f87ecdfd14fe26faef1da6a0099aa79a7ee Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=AE=B8=E6=9D=B0=E5=8F=8B=20Jieyou=20Xu=20=28Joe=29?=
 <39484203+jieyouxu@users.noreply.github.com>
Date: Sat, 4 Jan 2025 18:51:39 +0800
Subject: [PATCH] bootstrap: revamp `book!` macro

---
 src/bootstrap/src/core/build_steps/doc.rs | 79 ++++++++++++++++-------
 1 file changed, 54 insertions(+), 25 deletions(-)

diff --git a/src/bootstrap/src/core/build_steps/doc.rs b/src/bootstrap/src/core/build_steps/doc.rs
index 75edc8ff78128..f3bd5cb197cb3 100644
--- a/src/bootstrap/src/core/build_steps/doc.rs
+++ b/src/bootstrap/src/core/build_steps/doc.rs
@@ -20,10 +20,29 @@ use crate::core::builder::{
 use crate::core::config::{Config, TargetSelection};
 use crate::helpers::{is_path_in_submodule, symlink_dir, t, up_to_date};
 
+/// If the doc path is inside a submodule and is thus not the same as the submodule path, then we
+/// need to use the submodule path to checkout the submodule. The doc could be inside an submodule
+/// that is not checked out. Helper for [`book`].
+fn select_book_submodule_path<'a>(doc_path: &'a str, submodule_path: Option<&'a str>) -> &'a str {
+    submodule_path.unwrap_or(doc_path)
+}
+
 macro_rules! book {
-    ($($name:ident, $path:expr, $book_name:expr, $lang:expr ;)+) => {
-        $(
-            #[derive(Debug, Clone, Hash, PartialEq, Eq)]
+    (
+        $name:ident {
+            name: $book_name:expr,
+            // This can be *within* a submodule, e.g. `src/tools/cargo/src/doc`, compared to the
+            // submodule *itself*.
+            doc_path: $doc_path:expr
+            // Optional; only needed if `doc_path` is inside the submodule path, i.e. they are not
+            // the same.
+            $(, submodule_path: $submodule_path:expr )?
+            // Optional; only needed if the book has multi-lingual support.
+            $(, languages: $languages:expr )?
+            $( , )?
+        }
+    ) => {
+        #[derive(Debug, Clone, Hash, PartialEq, Eq)]
         pub struct $name {
             target: TargetSelection,
         }
@@ -34,49 +53,59 @@ macro_rules! book {
 
             fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
                 let builder = run.builder;
-                run.path($path).default_condition(builder.config.docs)
+                run.path($doc_path).default_condition(builder.config.docs)
             }
 
             fn make_run(run: RunConfig<'_>) {
-                run.builder.ensure($name {
-                    target: run.target,
-                });
+                run.builder.ensure($name { target: run.target });
             }
 
             fn run(self, builder: &Builder<'_>) {
-                if is_path_in_submodule(&builder, $path) {
-                    builder.require_submodule($path, None);
+                let path = select_book_submodule_path(
+                    $doc_path,
+                    None $( .or(Some($submodule_path)) )?,
+                );
+
+                if is_path_in_submodule(&builder, $doc_path) {
+                    builder.require_submodule(path, None);
                 }
 
+                #[allow(unused_assignments, unused_mut)]
+                let mut languages: Vec<&str> = vec![];
+                $( languages.extend($languages); )?
+
                 builder.ensure(RustbookSrc {
                     target: self.target,
                     name: $book_name.to_owned(),
-                    src: builder.src.join($path),
+                    src: builder.src.join($doc_path),
                     parent: Some(self),
-                    languages: $lang.into(),
+                    languages,
                     rustdoc_compiler: None,
                 })
             }
         }
-        )+
-    }
+    };
 }
 
 // NOTE: When adding a book here, make sure to ALSO build the book by
 // adding a build step in `src/bootstrap/code/builder/mod.rs`!
 // NOTE: Make sure to add the corresponding submodule when adding a new book.
-// FIXME: Make checking for a submodule automatic somehow (maybe by having a list of all submodules
-// and checking against it?).
-book!(
-    CargoBook, "src/tools/cargo/src/doc", "cargo", &[];
-    ClippyBook, "src/tools/clippy/book", "clippy", &[];
-    EditionGuide, "src/doc/edition-guide", "edition-guide", &[];
-    EmbeddedBook, "src/doc/embedded-book", "embedded-book", &[];
-    Nomicon, "src/doc/nomicon", "nomicon", &[];
-    RustByExample, "src/doc/rust-by-example", "rust-by-example", &["ja", "zh"];
-    RustdocBook, "src/doc/rustdoc", "rustdoc", &[];
-    StyleGuide, "src/doc/style-guide", "style-guide", &[];
-);
+book!(CargoBook {
+    name: "cargo",
+    doc_path: "src/tools/cargo/src/doc",
+    submodule_path: "src/tools/cargo",
+});
+book!(ClippyBook { name: "clippy", doc_path: "src/tools/clippy/book" });
+book!(EditionGuide { name: "edition-guide", doc_path: "src/doc/edition-guide" });
+book!(EmbeddedBook { name: "embedded-book", doc_path: "src/doc/embedded-book" });
+book!(Nomicon { name: "nomicon", doc_path: "src/doc/nomicon" });
+book!(RustByExample {
+    name: "rust-by-example",
+    doc_path: "src/doc/rust-by-example",
+    languages: &["ja", "zh"]
+});
+book!(RustdocBook { name: "rustdoc", doc_path: "src/doc/rustdoc" });
+book!(StyleGuide { name: "style-guide", doc_path: "src/doc/style-guide" });
 
 #[derive(Debug, Clone, Hash, PartialEq, Eq)]
 pub struct UnstableBook {