src/bootstrap/doc.rs

   1 //! Documentation generation for rustbuilder.
   2 //!
   3 //! This module implements generation for all bits and pieces of documentation
   4 //! for the Rust project. This notably includes suites like the rust book, the
   5 //! nomicon, rust by example, standalone documentation, etc.
   6 //!
   7 //! Everything here is basically just a shim around calling either `rustbook` or
   8 //! `rustdoc`.
   9
  10 use std::collections::HashSet;
  11 use std::fs;
  12 use std::io;
  13 use std::path::{Path, PathBuf};
  14
  15 use crate::builder::{Builder, Compiler, Kind, RunConfig, ShouldRun, Step};
  16 use crate::cache::{Interned, INTERNER};
  17 use crate::compile;
  18 use crate::config::{Config, TargetSelection};
  19 use crate::tool::{self, prepare_tool_cargo, SourceType, Tool};
  20 use crate::util::{symlink_dir, t, up_to_date};
  21 use crate::Mode;
  22
  23 macro_rules! submodule_helper {
  24     ($path:expr, submodule) => {
  25         $path
  26     };
  27     ($path:expr, submodule = $submodule:literal) => {
  28         $submodule
  29     };
  30 }
  31
  32 macro_rules! book {
  33     ($($name:ident, $path:expr, $book_name:expr $(, submodule $(= $submodule:literal)? )? ;)+) => {
  34         $(
  35             #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
  36         pub struct $name {
  37             target: TargetSelection,
  38         }
  39
  40         impl Step for $name {
  41             type Output = ();
  42             const DEFAULT: bool = true;
  43
  44             fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
  45                 let builder = run.builder;
  46                 run.path($path).default_condition(builder.config.docs)
  47             }
  48
  49             fn make_run(run: RunConfig<'_>) {
  50                 run.builder.ensure($name {
  51                     target: run.target,
  52                 });
  53             }
  54
  55             fn run(self, builder: &Builder<'_>) {
  56                 $(
  57                     let path = Path::new(submodule_helper!( $path, submodule $( = $submodule )? ));
  58                     builder.update_submodule(&path);
  59                 )?
  60                 builder.ensure(RustbookSrc {
  61                     target: self.target,
  62                     name: INTERNER.intern_str($book_name),
  63                     src: INTERNER.intern_path(builder.src.join($path)),
  64                 })
  65             }
  66         }
  67         )+
  68     }
  69 }
  70
  71 // NOTE: When adding a book here, make sure to ALSO build the book by
  72 // adding a build step in `src/bootstrap/builder.rs`!
  73 // NOTE: Make sure to add the corresponding submodule when adding a new book.
  74 // FIXME: Make checking for a submodule automatic somehow (maybe by having a list of all submodules
  75 // and checking against it?).
  76 book!(
  77     CargoBook, "src/tools/cargo/src/doc", "cargo", submodule = "src/tools/cargo";
  78     EditionGuide, "src/doc/edition-guide", "edition-guide", submodule;
  79     EmbeddedBook, "src/doc/embedded-book", "embedded-book", submodule;
  80     Nomicon, "src/doc/nomicon", "nomicon", submodule;
  81     Reference, "src/doc/reference", "reference", submodule;
  82     RustByExample, "src/doc/rust-by-example", "rust-by-example", submodule;
  83     RustdocBook, "src/doc/rustdoc", "rustdoc";
  84 );
  85
  86 fn open(builder: &Builder<'_>, path: impl AsRef<Path>) {
  87     if builder.config.dry_run || !builder.config.cmd.open() {
  88         return;
  89     }
  90
  91     let path = path.as_ref();
  92     builder.info(&format!("Opening doc {}", path.display()));
  93     if let Err(err) = opener::open(path) {
  94         builder.info(&format!("{}\n", err));
  95     }
  96 }
  97
  98 // "library/std" -> ["library", "std"]
  99 //
 100 // Used for deciding whether a particular step is one requested by the user on
 101 // the `x.py doc` command line, which determines whether `--open` will open that
 102 // page.
 103 pub(crate) fn components_simplified(path: &PathBuf) -> Vec<&str> {
 104     path.iter().map(|component| component.to_str().unwrap_or("???")).collect()
 105 }
 106
 107 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 108 pub struct UnstableBook {
 109     target: TargetSelection,
 110 }
 111
 112 impl Step for UnstableBook {
 113     type Output = ();
 114     const DEFAULT: bool = true;
 115
 116     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 117         let builder = run.builder;
 118         run.path("src/doc/unstable-book").default_condition(builder.config.docs)
 119     }
 120
 121     fn make_run(run: RunConfig<'_>) {
 122         run.builder.ensure(UnstableBook { target: run.target });
 123     }
 124
 125     fn run(self, builder: &Builder<'_>) {
 126         builder.ensure(UnstableBookGen { target: self.target });
 127         builder.ensure(RustbookSrc {
 128             target: self.target,
 129             name: INTERNER.intern_str("unstable-book"),
 130             src: INTERNER.intern_path(builder.md_doc_out(self.target).join("unstable-book")),
 131         })
 132     }
 133 }
 134
 135 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 136 struct RustbookSrc {
 137     target: TargetSelection,
 138     name: Interned<String>,
 139     src: Interned<PathBuf>,
 140 }
 141
 142 impl Step for RustbookSrc {
 143     type Output = ();
 144
 145     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 146         run.never()
 147     }
 148
 149     /// Invoke `rustbook` for `target` for the doc book `name` from the `src` path.
 150     ///
 151     /// This will not actually generate any documentation if the documentation has
 152     /// already been generated.
 153     fn run(self, builder: &Builder<'_>) {
 154         let target = self.target;
 155         let name = self.name;
 156         let src = self.src;
 157         let out = builder.doc_out(target);
 158         t!(fs::create_dir_all(&out));
 159
 160         let out = out.join(name);
 161         let index = out.join("index.html");
 162         let rustbook = builder.tool_exe(Tool::Rustbook);
 163         let mut rustbook_cmd = builder.tool_cmd(Tool::Rustbook);
 164         if builder.config.dry_run || up_to_date(&src, &index) && up_to_date(&rustbook, &index) {
 165             return;
 166         }
 167         builder.info(&format!("Rustbook ({}) - {}", target, name));
 168         let _ = fs::remove_dir_all(&out);
 169
 170         builder.run(rustbook_cmd.arg("build").arg(&src).arg("-d").arg(out));
 171     }
 172 }
 173
 174 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 175 pub struct TheBook {
 176     compiler: Compiler,
 177     target: TargetSelection,
 178 }
 179
 180 impl Step for TheBook {
 181     type Output = ();
 182     const DEFAULT: bool = true;
 183
 184     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 185         let builder = run.builder;
 186         run.path("src/doc/book").default_condition(builder.config.docs)
 187     }
 188
 189     fn make_run(run: RunConfig<'_>) {
 190         run.builder.ensure(TheBook {
 191             compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
 192             target: run.target,
 193         });
 194     }
 195
 196     /// Builds the book and associated stuff.
 197     ///
 198     /// We need to build:
 199     ///
 200     /// * Book
 201     /// * Older edition redirects
 202     /// * Version info and CSS
 203     /// * Index page
 204     /// * Redirect pages
 205     fn run(self, builder: &Builder<'_>) {
 206         let relative_path = Path::new("src").join("doc").join("book");
 207         builder.update_submodule(&relative_path);
 208
 209         let compiler = self.compiler;
 210         let target = self.target;
 211
 212         // build book
 213         builder.ensure(RustbookSrc {
 214             target,
 215             name: INTERNER.intern_str("book"),
 216             src: INTERNER.intern_path(builder.src.join(&relative_path)),
 217         });
 218
 219         // building older edition redirects
 220         for edition in &["first-edition", "second-edition", "2018-edition"] {
 221             builder.ensure(RustbookSrc {
 222                 target,
 223                 name: INTERNER.intern_string(format!("book/{}", edition)),
 224                 src: INTERNER.intern_path(builder.src.join(&relative_path).join(edition)),
 225             });
 226         }
 227
 228         // build the version info page and CSS
 229         builder.ensure(Standalone { compiler, target });
 230
 231         // build the redirect pages
 232         builder.info(&format!("Documenting book redirect pages ({})", target));
 233         for file in t!(fs::read_dir(builder.src.join(&relative_path).join("redirects"))) {
 234             let file = t!(file);
 235             let path = file.path();
 236             let path = path.to_str().unwrap();
 237
 238             invoke_rustdoc(builder, compiler, target, path);
 239         }
 240
 241         if builder.was_invoked_explicitly::<Self>(Kind::Doc) {
 242             let out = builder.doc_out(target);
 243             let index = out.join("book").join("index.html");
 244             open(builder, &index);
 245         }
 246     }
 247 }
 248
 249 fn invoke_rustdoc(
 250     builder: &Builder<'_>,
 251     compiler: Compiler,
 252     target: TargetSelection,
 253     markdown: &str,
 254 ) {
 255     let out = builder.doc_out(target);
 256
 257     let path = builder.src.join("src/doc").join(markdown);
 258
 259     let header = builder.src.join("src/doc/redirect.inc");
 260     let footer = builder.src.join("src/doc/footer.inc");
 261     let version_info = out.join("version_info.html");
 262
 263     let mut cmd = builder.rustdoc_cmd(compiler);
 264
 265     let out = out.join("book");
 266
 267     cmd.arg("--html-after-content")
 268         .arg(&footer)
 269         .arg("--html-before-content")
 270         .arg(&version_info)
 271         .arg("--html-in-header")
 272         .arg(&header)
 273         .arg("--markdown-no-toc")
 274         .arg("--markdown-playground-url")
 275         .arg("https://play.rust-lang.org/")
 276         .arg("-o")
 277         .arg(&out)
 278         .arg(&path)
 279         .arg("--markdown-css")
 280         .arg("../rust.css");
 281
 282     if !builder.config.docs_minification {
 283         cmd.arg("-Z").arg("unstable-options").arg("--disable-minification");
 284     }
 285
 286     builder.run(&mut cmd);
 287 }
 288
 289 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 290 pub struct Standalone {
 291     compiler: Compiler,
 292     target: TargetSelection,
 293 }
 294
 295 impl Step for Standalone {
 296     type Output = ();
 297     const DEFAULT: bool = true;
 298
 299     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 300         let builder = run.builder;
 301         run.path("src/doc").default_condition(builder.config.docs)
 302     }
 303
 304     fn make_run(run: RunConfig<'_>) {
 305         run.builder.ensure(Standalone {
 306             compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
 307             target: run.target,
 308         });
 309     }
 310
 311     /// Generates all standalone documentation as compiled by the rustdoc in `stage`
 312     /// for the `target` into `out`.
 313     ///
 314     /// This will list all of `src/doc` looking for markdown files and appropriately
 315     /// perform transformations like substituting `VERSION`, `SHORT_HASH`, and
 316     /// `STAMP` along with providing the various header/footer HTML we've customized.
 317     ///
 318     /// In the end, this is just a glorified wrapper around rustdoc!
 319     fn run(self, builder: &Builder<'_>) {
 320         let target = self.target;
 321         let compiler = self.compiler;
 322         builder.info(&format!("Documenting standalone ({})", target));
 323         let out = builder.doc_out(target);
 324         t!(fs::create_dir_all(&out));
 325
 326         let favicon = builder.src.join("src/doc/favicon.inc");
 327         let footer = builder.src.join("src/doc/footer.inc");
 328         let full_toc = builder.src.join("src/doc/full-toc.inc");
 329         t!(fs::copy(builder.src.join("src/doc/rust.css"), out.join("rust.css")));
 330
 331         let version_input = builder.src.join("src/doc/version_info.html.template");
 332         let version_info = out.join("version_info.html");
 333
 334         if !builder.config.dry_run && !up_to_date(&version_input, &version_info) {
 335             let info = t!(fs::read_to_string(&version_input))
 336                 .replace("VERSION", &builder.rust_release())
 337                 .replace("SHORT_HASH", builder.rust_info.sha_short().unwrap_or(""))
 338                 .replace("STAMP", builder.rust_info.sha().unwrap_or(""));
 339             t!(fs::write(&version_info, &info));
 340         }
 341
 342         for file in t!(fs::read_dir(builder.src.join("src/doc"))) {
 343             let file = t!(file);
 344             let path = file.path();
 345             let filename = path.file_name().unwrap().to_str().unwrap();
 346             if !filename.ends_with(".md") || filename == "README.md" {
 347                 continue;
 348             }
 349
 350             let html = out.join(filename).with_extension("html");
 351             let rustdoc = builder.rustdoc(compiler);
 352             if up_to_date(&path, &html)
 353                 && up_to_date(&footer, &html)
 354                 && up_to_date(&favicon, &html)
 355                 && up_to_date(&full_toc, &html)
 356                 && (builder.config.dry_run || up_to_date(&version_info, &html))
 357                 && (builder.config.dry_run || up_to_date(&rustdoc, &html))
 358             {
 359                 continue;
 360             }
 361
 362             let mut cmd = builder.rustdoc_cmd(compiler);
 363             // Needed for --index-page flag
 364             cmd.arg("-Z").arg("unstable-options");
 365
 366             cmd.arg("--html-after-content")
 367                 .arg(&footer)
 368                 .arg("--html-before-content")
 369                 .arg(&version_info)
 370                 .arg("--html-in-header")
 371                 .arg(&favicon)
 372                 .arg("--markdown-no-toc")
 373                 .arg("--index-page")
 374                 .arg(&builder.src.join("src/doc/index.md"))
 375                 .arg("--markdown-playground-url")
 376                 .arg("https://play.rust-lang.org/")
 377                 .arg("-o")
 378                 .arg(&out)
 379                 .arg(&path);
 380
 381             if !builder.config.docs_minification {
 382                 cmd.arg("--disable-minification");
 383             }
 384
 385             if filename == "not_found.md" {
 386                 cmd.arg("--markdown-css")
 387                     .arg(format!("https://doc.rust-lang.org/rustdoc{}.css", &builder.version))
 388                     .arg("--markdown-css")
 389                     .arg("https://doc.rust-lang.org/rust.css");
 390             } else {
 391                 cmd.arg("--markdown-css")
 392                     .arg(format!("rustdoc{}.css", &builder.version))
 393                     .arg("--markdown-css")
 394                     .arg("rust.css");
 395             }
 396             builder.run(&mut cmd);
 397         }
 398
 399         // We open doc/index.html as the default if invoked as `x.py doc --open`
 400         // with no particular explicit doc requested (e.g. library/core).
 401         if builder.paths.is_empty() || builder.was_invoked_explicitly::<Self>(Kind::Doc) {
 402             let index = out.join("index.html");
 403             open(builder, &index);
 404         }
 405     }
 406 }
 407
 408 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 409 pub struct Std {
 410     pub stage: u32,
 411     pub target: TargetSelection,
 412 }
 413
 414 impl Step for Std {
 415     type Output = ();
 416     const DEFAULT: bool = true;
 417
 418     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 419         let builder = run.builder;
 420         run.all_krates("test").default_condition(builder.config.docs)
 421     }
 422
 423     fn make_run(run: RunConfig<'_>) {
 424         run.builder.ensure(Std { stage: run.builder.top_stage, target: run.target });
 425     }
 426
 427     /// Compile all standard library documentation.
 428     ///
 429     /// This will generate all documentation for the standard library and its
 430     /// dependencies. This is largely just a wrapper around `cargo doc`.
 431     fn run(self, builder: &Builder<'_>) {
 432         let stage = self.stage;
 433         let target = self.target;
 434         builder.info(&format!("Documenting stage{} std ({})", stage, target));
 435         let out = builder.doc_out(target);
 436         t!(fs::create_dir_all(&out));
 437         let compiler = builder.compiler(stage, builder.config.build);
 438
 439         builder.ensure(compile::Std { compiler, target });
 440         let out_dir = builder.stage_out(compiler, Mode::Std).join(target.triple).join("doc");
 441
 442         t!(fs::copy(builder.src.join("src/doc/rust.css"), out.join("rust.css")));
 443
 444         let run_cargo_rustdoc_for = |package: &str| {
 445             let mut cargo =
 446                 builder.cargo(compiler, Mode::Std, SourceType::InTree, target, "rustdoc");
 447             compile::std_cargo(builder, target, compiler.stage, &mut cargo);
 448
 449             cargo
 450                 .arg("-p")
 451                 .arg(package)
 452                 .arg("-Zskip-rustdoc-fingerprint")
 453                 .arg("--")
 454                 .arg("--markdown-css")
 455                 .arg("rust.css")
 456                 .arg("--markdown-no-toc")
 457                 .arg("-Z")
 458                 .arg("unstable-options")
 459                 .arg("--resource-suffix")
 460                 .arg(&builder.version)
 461                 .arg("--index-page")
 462                 .arg(&builder.src.join("src/doc/index.md"));
 463
 464             if !builder.config.docs_minification {
 465                 cargo.arg("--disable-minification");
 466             }
 467
 468             builder.run(&mut cargo.into());
 469         };
 470
 471         let paths = builder
 472             .paths
 473             .iter()
 474             .map(components_simplified)
 475             .filter_map(|path| {
 476                 if path.get(0) == Some(&"library") {
 477                     Some(path[1].to_owned())
 478                 } else if !path.is_empty() {
 479                     Some(path[0].to_owned())
 480                 } else {
 481                     None
 482                 }
 483             })
 484             .collect::<Vec<_>>();
 485
 486         // Only build the following crates. While we could just iterate over the
 487         // folder structure, that would also build internal crates that we do
 488         // not want to show in documentation. These crates will later be visited
 489         // by the rustc step, so internal documentation will show them.
 490         //
 491         // Note that the order here is important! The crates need to be
 492         // processed starting from the leaves, otherwise rustdoc will not
 493         // create correct links between crates because rustdoc depends on the
 494         // existence of the output directories to know if it should be a local
 495         // or remote link.
 496         let krates = ["core", "alloc", "std", "proc_macro", "test"];
 497         for krate in &krates {
 498             run_cargo_rustdoc_for(krate);
 499             if paths.iter().any(|p| p == krate) {
 500                 // No need to document more of the libraries if we have the one we want.
 501                 break;
 502             }
 503         }
 504         builder.cp_r(&out_dir, &out);
 505
 506         // Look for library/std, library/core etc in the `x.py doc` arguments and
 507         // open the corresponding rendered docs.
 508         for requested_crate in paths {
 509             if krates.iter().any(|k| *k == requested_crate.as_str()) {
 510                 let index = out.join(requested_crate).join("index.html");
 511                 open(builder, &index);
 512             }
 513         }
 514     }
 515 }
 516
 517 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 518 pub struct Rustc {
 519     pub stage: u32,
 520     pub target: TargetSelection,
 521 }
 522
 523 impl Step for Rustc {
 524     type Output = ();
 525     const DEFAULT: bool = true;
 526     const ONLY_HOSTS: bool = true;
 527
 528     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 529         let builder = run.builder;
 530         run.krate("rustc-main").path("compiler").default_condition(builder.config.compiler_docs)
 531     }
 532
 533     fn make_run(run: RunConfig<'_>) {
 534         run.builder.ensure(Rustc { stage: run.builder.top_stage, target: run.target });
 535     }
 536
 537     /// Generates compiler documentation.
 538     ///
 539     /// This will generate all documentation for compiler and dependencies.
 540     /// Compiler documentation is distributed separately, so we make sure
 541     /// we do not merge it with the other documentation from std, test and
 542     /// proc_macros. This is largely just a wrapper around `cargo doc`.
 543     fn run(self, builder: &Builder<'_>) {
 544         let stage = self.stage;
 545         let target = self.target;
 546         builder.info(&format!("Documenting stage{} compiler ({})", stage, target));
 547
 548         let paths = builder
 549             .paths
 550             .iter()
 551             .map(components_simplified)
 552             .filter_map(|path| {
 553                 if path.get(0) == Some(&"compiler") {
 554                     path.get(1).map(|p| p.to_owned())
 555                 } else {
 556                     None
 557                 }
 558             })
 559             .collect::<Vec<_>>();
 560
 561         // This is the intended out directory for compiler documentation.
 562         let out = builder.compiler_doc_out(target);
 563         t!(fs::create_dir_all(&out));
 564
 565         // Build rustc.
 566         let compiler = builder.compiler(stage, builder.config.build);
 567         builder.ensure(compile::Rustc { compiler, target });
 568
 569         // This uses a shared directory so that librustdoc documentation gets
 570         // correctly built and merged with the rustc documentation. This is
 571         // needed because rustdoc is built in a different directory from
 572         // rustc. rustdoc needs to be able to see everything, for example when
 573         // merging the search index, or generating local (relative) links.
 574         let out_dir = builder.stage_out(compiler, Mode::Rustc).join(target.triple).join("doc");
 575         t!(symlink_dir_force(&builder.config, &out, &out_dir));
 576         // Cargo puts proc macros in `target/doc` even if you pass `--target`
 577         // explicitly (https://github.com/rust-lang/cargo/issues/7677).
 578         let proc_macro_out_dir = builder.stage_out(compiler, Mode::Rustc).join("doc");
 579         t!(symlink_dir_force(&builder.config, &out, &proc_macro_out_dir));
 580
 581         // Build cargo command.
 582         let mut cargo = builder.cargo(compiler, Mode::Rustc, SourceType::InTree, target, "doc");
 583         cargo.rustdocflag("--document-private-items");
 584         // Since we always pass --document-private-items, there's no need to warn about linking to private items.
 585         cargo.rustdocflag("-Arustdoc::private-intra-doc-links");
 586         cargo.rustdocflag("--enable-index-page");
 587         cargo.rustdocflag("-Zunstable-options");
 588         cargo.rustdocflag("-Znormalize-docs");
 589         cargo.rustdocflag("--show-type-layout");
 590         cargo.rustdocflag("--generate-link-to-definition");
 591         compile::rustc_cargo(builder, &mut cargo, target);
 592         cargo.arg("-Zunstable-options");
 593         cargo.arg("-Zskip-rustdoc-fingerprint");
 594
 595         // Only include compiler crates, no dependencies of those, such as `libc`.
 596         // Do link to dependencies on `docs.rs` however using `rustdoc-map`.
 597         cargo.arg("--no-deps");
 598         cargo.arg("-Zrustdoc-map");
 599
 600         // FIXME: `-Zrustdoc-map` does not yet correctly work for transitive dependencies,
 601         // once this is no longer an issue the special case for `ena` can be removed.
 602         cargo.rustdocflag("--extern-html-root-url");
 603         cargo.rustdocflag("ena=https://docs.rs/ena/latest/");
 604
 605         let mut compiler_crates = HashSet::new();
 606
 607         if paths.is_empty() {
 608             // Find dependencies for top level crates.
 609             for root_crate in &["rustc_driver", "rustc_codegen_llvm", "rustc_codegen_ssa"] {
 610                 compiler_crates.extend(
 611                     builder
 612                         .in_tree_crates(root_crate, Some(target))
 613                         .into_iter()
 614                         .map(|krate| krate.name),
 615                 );
 616             }
 617         } else {
 618             for root_crate in paths {
 619                 if !builder.src.join("compiler").join(&root_crate).exists() {
 620                     builder.info(&format!(
 621                         "\tskipping - compiler/{} (unknown compiler crate)",
 622                         root_crate
 623                     ));
 624                 } else {
 625                     compiler_crates.extend(
 626                         builder
 627                             .in_tree_crates(root_crate, Some(target))
 628                             .into_iter()
 629                             .map(|krate| krate.name),
 630                     );
 631                 }
 632             }
 633         }
 634
 635         let mut to_open = None;
 636         for krate in &compiler_crates {
 637             // Create all crate output directories first to make sure rustdoc uses
 638             // relative links.
 639             // FIXME: Cargo should probably do this itself.
 640             t!(fs::create_dir_all(out_dir.join(krate)));
 641             cargo.arg("-p").arg(krate);
 642             if to_open.is_none() {
 643                 to_open = Some(krate);
 644             }
 645         }
 646
 647         builder.run(&mut cargo.into());
 648         // Let's open the first crate documentation page:
 649         if let Some(krate) = to_open {
 650             let index = out.join(krate).join("index.html");
 651             open(builder, &index);
 652         }
 653     }
 654 }
 655
 656 macro_rules! tool_doc {
 657     ($tool: ident, $should_run: literal, $path: literal, [$($krate: literal),+ $(,)?] $(,)?) => {
 658         #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 659         pub struct $tool {
 660             stage: u32,
 661             target: TargetSelection,
 662         }
 663
 664         impl Step for $tool {
 665             type Output = ();
 666             const DEFAULT: bool = true;
 667             const ONLY_HOSTS: bool = true;
 668
 669             fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 670                 let builder = run.builder;
 671                 run.krate($should_run).default_condition(builder.config.compiler_docs)
 672             }
 673
 674             fn make_run(run: RunConfig<'_>) {
 675                 run.builder.ensure($tool { stage: run.builder.top_stage, target: run.target });
 676             }
 677
 678             /// Generates compiler documentation.
 679             ///
 680             /// This will generate all documentation for compiler and dependencies.
 681             /// Compiler documentation is distributed separately, so we make sure
 682             /// we do not merge it with the other documentation from std, test and
 683             /// proc_macros. This is largely just a wrapper around `cargo doc`.
 684             fn run(self, builder: &Builder<'_>) {
 685                 let stage = self.stage;
 686                 let target = self.target;
 687                 builder.info(
 688                     &format!(
 689                         "Documenting stage{} {} ({})",
 690                         stage,
 691                         stringify!($tool).to_lowercase(),
 692                         target,
 693                     ),
 694                 );
 695
 696                 // This is the intended out directory for compiler documentation.
 697                 let out = builder.compiler_doc_out(target);
 698                 t!(fs::create_dir_all(&out));
 699
 700                 let compiler = builder.compiler(stage, builder.config.build);
 701
 702                 // Build rustc docs so that we generate relative links.
 703                 builder.ensure(Rustc { stage, target });
 704
 705                 // Symlink compiler docs to the output directory of rustdoc documentation.
 706                 let out_dir = builder.stage_out(compiler, Mode::ToolRustc).join(target.triple).join("doc");
 707                 t!(fs::create_dir_all(&out_dir));
 708                 t!(symlink_dir_force(&builder.config, &out, &out_dir));
 709
 710                 // Build cargo command.
 711                 let mut cargo = prepare_tool_cargo(
 712                     builder,
 713                     compiler,
 714                     Mode::ToolRustc,
 715                     target,
 716                     "doc",
 717                     $path,
 718                     SourceType::InTree,
 719                     &[],
 720                 );
 721
 722                 cargo.arg("-Zskip-rustdoc-fingerprint");
 723                 // Only include compiler crates, no dependencies of those, such as `libc`.
 724                 cargo.arg("--no-deps");
 725                 $(
 726                     cargo.arg("-p").arg($krate);
 727                 )+
 728
 729                 cargo.rustdocflag("--document-private-items");
 730                 cargo.rustdocflag("--enable-index-page");
 731                 cargo.rustdocflag("--show-type-layout");
 732                 cargo.rustdocflag("--generate-link-to-definition");
 733                 cargo.rustdocflag("-Zunstable-options");
 734                 builder.run(&mut cargo.into());
 735             }
 736         }
 737     }
 738 }
 739
 740 tool_doc!(Rustdoc, "rustdoc-tool", "src/tools/rustdoc", ["rustdoc", "rustdoc-json-types"]);
 741 tool_doc!(
 742     Rustfmt,
 743     "rustfmt-nightly",
 744     "src/tools/rustfmt",
 745     ["rustfmt-nightly", "rustfmt-config_proc_macro"],
 746 );
 747 tool_doc!(Clippy, "clippy", "src/tools/clippy", ["clippy_utils"]);
 748
 749 #[derive(Ord, PartialOrd, Debug, Copy, Clone, Hash, PartialEq, Eq)]
 750 pub struct ErrorIndex {
 751     pub target: TargetSelection,
 752 }
 753
 754 impl Step for ErrorIndex {
 755     type Output = ();
 756     const DEFAULT: bool = true;
 757     const ONLY_HOSTS: bool = true;
 758
 759     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 760         let builder = run.builder;
 761         run.path("src/tools/error_index_generator").default_condition(builder.config.docs)
 762     }
 763
 764     fn make_run(run: RunConfig<'_>) {
 765         let target = run.target;
 766         run.builder.ensure(ErrorIndex { target });
 767     }
 768
 769     /// Generates the HTML rendered error-index by running the
 770     /// `error_index_generator` tool.
 771     fn run(self, builder: &Builder<'_>) {
 772         builder.info(&format!("Documenting error index ({})", self.target));
 773         let out = builder.doc_out(self.target);
 774         t!(fs::create_dir_all(&out));
 775         let mut index = tool::ErrorIndex::command(builder);
 776         index.arg("html");
 777         index.arg(out.join("error-index.html"));
 778         index.arg(&builder.version);
 779
 780         builder.run(&mut index);
 781     }
 782 }
 783
 784 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 785 pub struct UnstableBookGen {
 786     target: TargetSelection,
 787 }
 788
 789 impl Step for UnstableBookGen {
 790     type Output = ();
 791     const DEFAULT: bool = true;
 792     const ONLY_HOSTS: bool = true;
 793
 794     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 795         let builder = run.builder;
 796         run.path("src/tools/unstable-book-gen").default_condition(builder.config.docs)
 797     }
 798
 799     fn make_run(run: RunConfig<'_>) {
 800         run.builder.ensure(UnstableBookGen { target: run.target });
 801     }
 802
 803     fn run(self, builder: &Builder<'_>) {
 804         let target = self.target;
 805
 806         builder.info(&format!("Generating unstable book md files ({})", target));
 807         let out = builder.md_doc_out(target).join("unstable-book");
 808         builder.create_dir(&out);
 809         builder.remove_dir(&out);
 810         let mut cmd = builder.tool_cmd(Tool::UnstableBookGen);
 811         cmd.arg(builder.src.join("library"));
 812         cmd.arg(builder.src.join("compiler"));
 813         cmd.arg(builder.src.join("src"));
 814         cmd.arg(out);
 815
 816         builder.run(&mut cmd);
 817     }
 818 }
 819
 820 fn symlink_dir_force(config: &Config, src: &Path, dst: &Path) -> io::Result<()> {
 821     if config.dry_run {
 822         return Ok(());
 823     }
 824     if let Ok(m) = fs::symlink_metadata(dst) {
 825         if m.file_type().is_dir() {
 826             fs::remove_dir_all(dst)?;
 827         } else {
 828             // handle directory junctions on windows by falling back to
 829             // `remove_dir`.
 830             fs::remove_file(dst).or_else(|_| fs::remove_dir(dst))?;
 831         }
 832     }
 833
 834     symlink_dir(config, src, dst)
 835 }
 836
 837 #[derive(Ord, PartialOrd, Debug, Copy, Clone, Hash, PartialEq, Eq)]
 838 pub struct RustcBook {
 839     pub compiler: Compiler,
 840     pub target: TargetSelection,
 841     pub validate: bool,
 842 }
 843
 844 impl Step for RustcBook {
 845     type Output = ();
 846     const DEFAULT: bool = true;
 847     const ONLY_HOSTS: bool = true;
 848
 849     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 850         let builder = run.builder;
 851         run.path("src/doc/rustc").default_condition(builder.config.docs)
 852     }
 853
 854     fn make_run(run: RunConfig<'_>) {
 855         run.builder.ensure(RustcBook {
 856             compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
 857             target: run.target,
 858             validate: false,
 859         });
 860     }
 861
 862     /// Builds the rustc book.
 863     ///
 864     /// The lints are auto-generated by a tool, and then merged into the book
 865     /// in the "md-doc" directory in the build output directory. Then
 866     /// "rustbook" is used to convert it to HTML.
 867     fn run(self, builder: &Builder<'_>) {
 868         let out_base = builder.md_doc_out(self.target).join("rustc");
 869         t!(fs::create_dir_all(&out_base));
 870         let out_listing = out_base.join("src/lints");
 871         builder.cp_r(&builder.src.join("src/doc/rustc"), &out_base);
 872         builder.info(&format!("Generating lint docs ({})", self.target));
 873
 874         let rustc = builder.rustc(self.compiler);
 875         // The tool runs `rustc` for extracting output examples, so it needs a
 876         // functional sysroot.
 877         builder.ensure(compile::Std { compiler: self.compiler, target: self.target });
 878         let mut cmd = builder.tool_cmd(Tool::LintDocs);
 879         cmd.arg("--src");
 880         cmd.arg(builder.src.join("compiler"));
 881         cmd.arg("--out");
 882         cmd.arg(&out_listing);
 883         cmd.arg("--rustc");
 884         cmd.arg(&rustc);
 885         cmd.arg("--rustc-target").arg(&self.target.rustc_target_arg());
 886         if builder.config.verbose() {
 887             cmd.arg("--verbose");
 888         }
 889         if self.validate {
 890             cmd.arg("--validate");
 891         }
 892         // If the lib directories are in an unusual location (changed in
 893         // config.toml), then this needs to explicitly update the dylib search
 894         // path.
 895         builder.add_rustc_lib_path(self.compiler, &mut cmd);
 896         builder.run(&mut cmd);
 897         // Run rustbook/mdbook to generate the HTML pages.
 898         builder.ensure(RustbookSrc {
 899             target: self.target,
 900             name: INTERNER.intern_str("rustc"),
 901             src: INTERNER.intern_path(out_base),
 902         });
 903         if builder.was_invoked_explicitly::<Self>(Kind::Doc) {
 904             let out = builder.doc_out(self.target);
 905             let index = out.join("rustc").join("index.html");
 906             open(builder, &index);
 907         }
 908     }
 909 }