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