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