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::ffi::OsStr;
  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     ClippyBook, "src/tools/clippy/book", "clippy";
  79     EditionGuide, "src/doc/edition-guide", "edition-guide", submodule;
  80     EmbeddedBook, "src/doc/embedded-book", "embedded-book", submodule;
  81     Nomicon, "src/doc/nomicon", "nomicon", submodule;
  82     Reference, "src/doc/reference", "reference", submodule;
  83     RustByExample, "src/doc/rust-by-example", "rust-by-example", submodule;
  84     RustdocBook, "src/doc/rustdoc", "rustdoc";
  85     StyleGuide, "src/doc/style-guide", "style-guide";
  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         let shared_assets = builder.ensure(SharedAssets { 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, &shared_assets, target, path);
 241         }
 242
 243         if builder.was_invoked_explicitly::<Self>(Kind::Doc) {
 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     shared_assets: &SharedAssetsPaths,
 255     target: TargetSelection,
 256     markdown: &str,
 257 ) {
 258     let out = builder.doc_out(target);
 259
 260     let path = builder.src.join("src/doc").join(markdown);
 261
 262     let header = builder.src.join("src/doc/redirect.inc");
 263     let footer = builder.src.join("src/doc/footer.inc");
 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(&shared_assets.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").alias("standalone").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 version_info = builder.ensure(SharedAssets { target: self.target }).version_info;
 329
 330         let favicon = builder.src.join("src/doc/favicon.inc");
 331         let footer = builder.src.join("src/doc/footer.inc");
 332         let full_toc = builder.src.join("src/doc/full-toc.inc");
 333
 334         for file in t!(fs::read_dir(builder.src.join("src/doc"))) {
 335             let file = t!(file);
 336             let path = file.path();
 337             let filename = path.file_name().unwrap().to_str().unwrap();
 338             if !filename.ends_with(".md") || filename == "README.md" {
 339                 continue;
 340             }
 341
 342             let html = out.join(filename).with_extension("html");
 343             let rustdoc = builder.rustdoc(compiler);
 344             if up_to_date(&path, &html)
 345                 && up_to_date(&footer, &html)
 346                 && up_to_date(&favicon, &html)
 347                 && up_to_date(&full_toc, &html)
 348                 && (builder.config.dry_run || up_to_date(&version_info, &html))
 349                 && (builder.config.dry_run || up_to_date(&rustdoc, &html))
 350             {
 351                 continue;
 352             }
 353
 354             let mut cmd = builder.rustdoc_cmd(compiler);
 355             // Needed for --index-page flag
 356             cmd.arg("-Z").arg("unstable-options");
 357
 358             cmd.arg("--html-after-content")
 359                 .arg(&footer)
 360                 .arg("--html-before-content")
 361                 .arg(&version_info)
 362                 .arg("--html-in-header")
 363                 .arg(&favicon)
 364                 .arg("--markdown-no-toc")
 365                 .arg("--index-page")
 366                 .arg(&builder.src.join("src/doc/index.md"))
 367                 .arg("--markdown-playground-url")
 368                 .arg("https://play.rust-lang.org/")
 369                 .arg("-o")
 370                 .arg(&out)
 371                 .arg(&path);
 372
 373             if !builder.config.docs_minification {
 374                 cmd.arg("--disable-minification");
 375             }
 376
 377             if filename == "not_found.md" {
 378                 cmd.arg("--markdown-css").arg("https://doc.rust-lang.org/rust.css");
 379             } else {
 380                 cmd.arg("--markdown-css").arg("rust.css");
 381             }
 382             builder.run(&mut cmd);
 383         }
 384
 385         // We open doc/index.html as the default if invoked as `x.py doc --open`
 386         // with no particular explicit doc requested (e.g. library/core).
 387         if builder.paths.is_empty() || builder.was_invoked_explicitly::<Self>(Kind::Doc) {
 388             let index = out.join("index.html");
 389             open(builder, &index);
 390         }
 391     }
 392 }
 393
 394 #[derive(Debug, Clone)]
 395 pub struct SharedAssetsPaths {
 396     pub version_info: PathBuf,
 397 }
 398
 399 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 400 pub struct SharedAssets {
 401     target: TargetSelection,
 402 }
 403
 404 impl Step for SharedAssets {
 405     type Output = SharedAssetsPaths;
 406     const DEFAULT: bool = false;
 407
 408     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 409         // Other tasks depend on this, no need to execute it on its own
 410         run.never()
 411     }
 412
 413     // Generate shared resources used by other pieces of documentation.
 414     fn run(self, builder: &Builder<'_>) -> Self::Output {
 415         let out = builder.doc_out(self.target);
 416
 417         let version_input = builder.src.join("src").join("doc").join("version_info.html.template");
 418         let version_info = out.join("version_info.html");
 419         if !builder.config.dry_run && !up_to_date(&version_input, &version_info) {
 420             let info = t!(fs::read_to_string(&version_input))
 421                 .replace("VERSION", &builder.rust_release())
 422                 .replace("SHORT_HASH", builder.rust_info.sha_short().unwrap_or(""))
 423                 .replace("STAMP", builder.rust_info.sha().unwrap_or(""));
 424             t!(fs::write(&version_info, &info));
 425         }
 426
 427         builder.copy(&builder.src.join("src").join("doc").join("rust.css"), &out.join("rust.css"));
 428
 429         SharedAssetsPaths { version_info }
 430     }
 431 }
 432
 433 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 434 pub struct Std {
 435     pub stage: u32,
 436     pub target: TargetSelection,
 437 }
 438
 439 impl Step for Std {
 440     type Output = ();
 441     const DEFAULT: bool = true;
 442
 443     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 444         let builder = run.builder;
 445         run.all_krates("test").path("library").default_condition(builder.config.docs)
 446     }
 447
 448     fn make_run(run: RunConfig<'_>) {
 449         run.builder.ensure(Std { stage: run.builder.top_stage, target: run.target });
 450     }
 451
 452     /// Compile all standard library documentation.
 453     ///
 454     /// This will generate all documentation for the standard library and its
 455     /// dependencies. This is largely just a wrapper around `cargo doc`.
 456     fn run(self, builder: &Builder<'_>) {
 457         let stage = self.stage;
 458         let target = self.target;
 459         let out = builder.doc_out(target);
 460         t!(fs::create_dir_all(&out));
 461
 462         builder.ensure(SharedAssets { target: self.target });
 463
 464         let index_page = builder.src.join("src/doc/index.md").into_os_string();
 465         let mut extra_args = vec![
 466             OsStr::new("--markdown-css"),
 467             OsStr::new("rust.css"),
 468             OsStr::new("--markdown-no-toc"),
 469             OsStr::new("--index-page"),
 470             &index_page,
 471         ];
 472
 473         if !builder.config.docs_minification {
 474             extra_args.push(OsStr::new("--disable-minification"));
 475         }
 476
 477         let requested_crates = builder
 478             .paths
 479             .iter()
 480             .map(components_simplified)
 481             .filter_map(|path| {
 482                 if path.len() >= 2 && path.get(0) == Some(&"library") {
 483                     // single crate
 484                     Some(path[1].to_owned())
 485                 } else if !path.is_empty() {
 486                     // ??
 487                     Some(path[0].to_owned())
 488                 } else {
 489                     // all library crates
 490                     None
 491                 }
 492             })
 493             .collect::<Vec<_>>();
 494
 495         doc_std(
 496             builder,
 497             DocumentationFormat::HTML,
 498             stage,
 499             target,
 500             &out,
 501             &extra_args,
 502             &requested_crates,
 503         );
 504
 505         // Look for library/std, library/core etc in the `x.py doc` arguments and
 506         // open the corresponding rendered docs.
 507         for requested_crate in requested_crates {
 508             if STD_PUBLIC_CRATES.iter().any(|k| *k == requested_crate.as_str()) {
 509                 let index = out.join(requested_crate).join("index.html");
 510                 open(builder, &index);
 511             }
 512         }
 513     }
 514 }
 515
 516 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 517 pub struct JsonStd {
 518     pub stage: u32,
 519     pub target: TargetSelection,
 520 }
 521
 522 impl Step for JsonStd {
 523     type Output = ();
 524     const DEFAULT: bool = false;
 525
 526     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 527         let default = run.builder.config.docs && run.builder.config.cmd.json();
 528         run.all_krates("test").path("library").default_condition(default)
 529     }
 530
 531     fn make_run(run: RunConfig<'_>) {
 532         run.builder.ensure(Std { stage: run.builder.top_stage, target: run.target });
 533     }
 534
 535     /// Build JSON documentation for the standard library crates.
 536     ///
 537     /// This is largely just a wrapper around `cargo doc`.
 538     fn run(self, builder: &Builder<'_>) {
 539         let stage = self.stage;
 540         let target = self.target;
 541         let out = builder.json_doc_out(target);
 542         t!(fs::create_dir_all(&out));
 543         let extra_args = [OsStr::new("--output-format"), OsStr::new("json")];
 544         doc_std(builder, DocumentationFormat::JSON, stage, target, &out, &extra_args, &[])
 545     }
 546 }
 547
 548 /// Name of the crates that are visible to consumers of the standard library.
 549 /// Documentation for internal crates is handled by the rustc step, so internal crates will show
 550 /// up there.
 551 ///
 552 /// Order here is important!
 553 /// Crates need to be processed starting from the leaves, otherwise rustdoc will not
 554 /// create correct links between crates because rustdoc depends on the
 555 /// existence of the output directories to know if it should be a local
 556 /// or remote link.
 557 const STD_PUBLIC_CRATES: [&str; 5] = ["core", "alloc", "std", "proc_macro", "test"];
 558
 559 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 560 enum DocumentationFormat {
 561     HTML,
 562     JSON,
 563 }
 564
 565 impl DocumentationFormat {
 566     fn as_str(&self) -> &str {
 567         match self {
 568             DocumentationFormat::HTML => "HTML",
 569             DocumentationFormat::JSON => "JSON",
 570         }
 571     }
 572 }
 573
 574 /// Build the documentation for public standard library crates.
 575 ///
 576 /// `requested_crates` can be used to build only a subset of the crates. If empty, all crates will
 577 /// be built.
 578 fn doc_std(
 579     builder: &Builder<'_>,
 580     format: DocumentationFormat,
 581     stage: u32,
 582     target: TargetSelection,
 583     out: &Path,
 584     extra_args: &[&OsStr],
 585     requested_crates: &[String],
 586 ) {
 587     builder.info(&format!(
 588         "Documenting stage{} std ({}) in {} format",
 589         stage,
 590         target,
 591         format.as_str()
 592     ));
 593     if builder.no_std(target) == Some(true) {
 594         panic!(
 595             "building std documentation for no_std target {target} is not supported\n\
 596              Set `docs = false` in the config to disable documentation."
 597         );
 598     }
 599     let compiler = builder.compiler(stage, builder.config.build);
 600     // This is directory where the compiler will place the output of the command.
 601     // We will then copy the files from this directory into the final `out` directory, the specified
 602     // as a function parameter.
 603     let out_dir = builder.stage_out(compiler, Mode::Std).join(target.triple).join("doc");
 604     // `cargo` uses the same directory for both JSON docs and HTML docs.
 605     // This could lead to cross-contamination when copying files into the specified `out` directory.
 606     // For example:
 607     // ```bash
 608     // x doc std
 609     // x doc std --json
 610     // ```
 611     // could lead to HTML docs being copied into the JSON docs output directory.
 612     // To avoid this issue, we clean the doc folder before invoking `cargo`.
 613     if out_dir.exists() {
 614         builder.remove_dir(&out_dir);
 615     }
 616
 617     let run_cargo_rustdoc_for = |package: &str| {
 618         let mut cargo = builder.cargo(compiler, Mode::Std, SourceType::InTree, target, "rustdoc");
 619         compile::std_cargo(builder, target, compiler.stage, &mut cargo);
 620         cargo
 621             .arg("-p")
 622             .arg(package)
 623             .arg("-Zskip-rustdoc-fingerprint")
 624             .arg("--")
 625             .arg("-Z")
 626             .arg("unstable-options")
 627             .arg("--resource-suffix")
 628             .arg(&builder.version)
 629             .args(extra_args);
 630         builder.run(&mut cargo.into());
 631     };
 632
 633     for krate in STD_PUBLIC_CRATES {
 634         run_cargo_rustdoc_for(krate);
 635         if requested_crates.iter().any(|p| p == krate) {
 636             // No need to document more of the libraries if we have the one we want.
 637             break;
 638         }
 639     }
 640
 641     builder.cp_r(&out_dir, &out);
 642 }
 643
 644 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 645 pub struct Rustc {
 646     pub stage: u32,
 647     pub target: TargetSelection,
 648 }
 649
 650 impl Step for Rustc {
 651     type Output = ();
 652     const DEFAULT: bool = true;
 653     const ONLY_HOSTS: bool = true;
 654
 655     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 656         let builder = run.builder;
 657         run.crate_or_deps("rustc-main")
 658             .path("compiler")
 659             .default_condition(builder.config.compiler_docs)
 660     }
 661
 662     fn make_run(run: RunConfig<'_>) {
 663         run.builder.ensure(Rustc { stage: run.builder.top_stage, target: run.target });
 664     }
 665
 666     /// Generates compiler documentation.
 667     ///
 668     /// This will generate all documentation for compiler and dependencies.
 669     /// Compiler documentation is distributed separately, so we make sure
 670     /// we do not merge it with the other documentation from std, test and
 671     /// proc_macros. This is largely just a wrapper around `cargo doc`.
 672     fn run(self, builder: &Builder<'_>) {
 673         let stage = self.stage;
 674         let target = self.target;
 675
 676         let paths = builder
 677             .paths
 678             .iter()
 679             .filter(|path| {
 680                 let components = components_simplified(path);
 681                 components.len() >= 2 && components[0] == "compiler"
 682             })
 683             .collect::<Vec<_>>();
 684
 685         // This is the intended out directory for compiler documentation.
 686         let out = builder.compiler_doc_out(target);
 687         t!(fs::create_dir_all(&out));
 688
 689         // Build the standard library, so that proc-macros can use it.
 690         // (Normally, only the metadata would be necessary, but proc-macros are special since they run at compile-time.)
 691         let compiler = builder.compiler(stage, builder.config.build);
 692         builder.ensure(compile::Std::new(compiler, builder.config.build));
 693
 694         builder.info(&format!("Documenting stage{} compiler ({})", stage, target));
 695
 696         // This uses a shared directory so that librustdoc documentation gets
 697         // correctly built and merged with the rustc documentation. This is
 698         // needed because rustdoc is built in a different directory from
 699         // rustc. rustdoc needs to be able to see everything, for example when
 700         // merging the search index, or generating local (relative) links.
 701         let out_dir = builder.stage_out(compiler, Mode::Rustc).join(target.triple).join("doc");
 702         t!(symlink_dir_force(&builder.config, &out, &out_dir));
 703         // Cargo puts proc macros in `target/doc` even if you pass `--target`
 704         // explicitly (https://github.com/rust-lang/cargo/issues/7677).
 705         let proc_macro_out_dir = builder.stage_out(compiler, Mode::Rustc).join("doc");
 706         t!(symlink_dir_force(&builder.config, &out, &proc_macro_out_dir));
 707
 708         // Build cargo command.
 709         let mut cargo = builder.cargo(compiler, Mode::Rustc, SourceType::InTree, target, "doc");
 710         cargo.rustdocflag("--document-private-items");
 711         // Since we always pass --document-private-items, there's no need to warn about linking to private items.
 712         cargo.rustdocflag("-Arustdoc::private-intra-doc-links");
 713         cargo.rustdocflag("--enable-index-page");
 714         cargo.rustdocflag("-Zunstable-options");
 715         cargo.rustdocflag("-Znormalize-docs");
 716         cargo.rustdocflag("--show-type-layout");
 717         cargo.rustdocflag("--generate-link-to-definition");
 718         compile::rustc_cargo(builder, &mut cargo, target);
 719         cargo.arg("-Zunstable-options");
 720         cargo.arg("-Zskip-rustdoc-fingerprint");
 721
 722         // Only include compiler crates, no dependencies of those, such as `libc`.
 723         // Do link to dependencies on `docs.rs` however using `rustdoc-map`.
 724         cargo.arg("--no-deps");
 725         cargo.arg("-Zrustdoc-map");
 726
 727         // FIXME: `-Zrustdoc-map` does not yet correctly work for transitive dependencies,
 728         // once this is no longer an issue the special case for `ena` can be removed.
 729         cargo.rustdocflag("--extern-html-root-url");
 730         cargo.rustdocflag("ena=https://docs.rs/ena/latest/");
 731
 732         let root_crates = if paths.is_empty() {
 733             vec![
 734                 INTERNER.intern_str("rustc_driver"),
 735                 INTERNER.intern_str("rustc_codegen_llvm"),
 736                 INTERNER.intern_str("rustc_codegen_ssa"),
 737             ]
 738         } else {
 739             paths.into_iter().map(|p| builder.crate_paths[p]).collect()
 740         };
 741         // Find dependencies for top level crates.
 742         let compiler_crates = root_crates.iter().flat_map(|krate| {
 743             builder.in_tree_crates(krate, Some(target)).into_iter().map(|krate| krate.name)
 744         });
 745
 746         let mut to_open = None;
 747         for krate in compiler_crates {
 748             // Create all crate output directories first to make sure rustdoc uses
 749             // relative links.
 750             // FIXME: Cargo should probably do this itself.
 751             t!(fs::create_dir_all(out_dir.join(krate)));
 752             cargo.arg("-p").arg(krate);
 753             if to_open.is_none() {
 754                 to_open = Some(krate);
 755             }
 756         }
 757
 758         builder.run(&mut cargo.into());
 759         // Let's open the first crate documentation page:
 760         if let Some(krate) = to_open {
 761             let index = out.join(krate).join("index.html");
 762             open(builder, &index);
 763         }
 764     }
 765 }
 766
 767 macro_rules! tool_doc {
 768     ($tool: ident, $should_run: literal, $path: literal, [$($krate: literal),+ $(,)?], in_tree = $in_tree:expr $(,)?) => {
 769         #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 770         pub struct $tool {
 771             target: TargetSelection,
 772         }
 773
 774         impl Step for $tool {
 775             type Output = ();
 776             const DEFAULT: bool = true;
 777             const ONLY_HOSTS: bool = true;
 778
 779             fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 780                 let builder = run.builder;
 781                 run.crate_or_deps($should_run).default_condition(builder.config.compiler_docs)
 782             }
 783
 784             fn make_run(run: RunConfig<'_>) {
 785                 run.builder.ensure($tool { target: run.target });
 786             }
 787
 788             /// Generates compiler documentation.
 789             ///
 790             /// This will generate all documentation for compiler and dependencies.
 791             /// Compiler documentation is distributed separately, so we make sure
 792             /// we do not merge it with the other documentation from std, test and
 793             /// proc_macros. This is largely just a wrapper around `cargo doc`.
 794             fn run(self, builder: &Builder<'_>) {
 795                 let stage = builder.top_stage;
 796                 let target = self.target;
 797
 798                 // This is the intended out directory for compiler documentation.
 799                 let out = builder.compiler_doc_out(target);
 800                 t!(fs::create_dir_all(&out));
 801
 802                 // Build rustc docs so that we generate relative links.
 803                 builder.ensure(Rustc { stage, target });
 804                 // Rustdoc needs the rustc sysroot available to build.
 805                 // FIXME: is there a way to only ensure `check::Rustc` here? Last time I tried it failed
 806                 // with strange errors, but only on a full bors test ...
 807                 let compiler = builder.compiler(stage, builder.config.build);
 808                 builder.ensure(compile::Rustc::new(compiler, target));
 809
 810                 builder.info(
 811                     &format!(
 812                         "Documenting stage{} {} ({})",
 813                         stage,
 814                         stringify!($tool).to_lowercase(),
 815                         target,
 816                     ),
 817                 );
 818
 819                 // Symlink compiler docs to the output directory of rustdoc documentation.
 820                 let out_dir = builder.stage_out(compiler, Mode::ToolRustc).join(target.triple).join("doc");
 821                 t!(fs::create_dir_all(&out_dir));
 822                 t!(symlink_dir_force(&builder.config, &out, &out_dir));
 823
 824                 let source_type = if $in_tree == true {
 825                     SourceType::InTree
 826                 } else {
 827                     SourceType::Submodule
 828                 };
 829
 830                 // Build cargo command.
 831                 let mut cargo = prepare_tool_cargo(
 832                     builder,
 833                     compiler,
 834                     Mode::ToolRustc,
 835                     target,
 836                     "doc",
 837                     $path,
 838                     source_type,
 839                     &[],
 840                 );
 841
 842                 cargo.arg("-Zskip-rustdoc-fingerprint");
 843                 // Only include compiler crates, no dependencies of those, such as `libc`.
 844                 cargo.arg("--no-deps");
 845                 $(
 846                     cargo.arg("-p").arg($krate);
 847                 )+
 848
 849                 cargo.rustdocflag("--document-private-items");
 850                 cargo.rustdocflag("--enable-index-page");
 851                 cargo.rustdocflag("--show-type-layout");
 852                 cargo.rustdocflag("--generate-link-to-definition");
 853                 cargo.rustdocflag("-Zunstable-options");
 854                 if $in_tree == true {
 855                     builder.run(&mut cargo.into());
 856                 } else {
 857                     // Allow out-of-tree docs to fail (since the tool might be in a broken state).
 858                     if !builder.try_run(&mut cargo.into()) {
 859                         builder.info(&format!(
 860                             "WARNING: tool {} failed to document; ignoring failure because it is an out-of-tree tool",
 861                             stringify!($tool).to_lowercase(),
 862                         ));
 863                     }
 864                 }
 865             }
 866         }
 867     }
 868 }
 869
 870 tool_doc!(
 871     Rustdoc,
 872     "rustdoc-tool",
 873     "src/tools/rustdoc",
 874     ["rustdoc", "rustdoc-json-types"],
 875     in_tree = true
 876 );
 877 tool_doc!(
 878     Rustfmt,
 879     "rustfmt-nightly",
 880     "src/tools/rustfmt",
 881     ["rustfmt-nightly", "rustfmt-config_proc_macro"],
 882     in_tree = true
 883 );
 884 tool_doc!(Clippy, "clippy", "src/tools/clippy", ["clippy_utils"], in_tree = true);
 885 tool_doc!(Miri, "miri", "src/tools/miri", ["miri"], in_tree = false);
 886
 887 #[derive(Ord, PartialOrd, Debug, Copy, Clone, Hash, PartialEq, Eq)]
 888 pub struct ErrorIndex {
 889     pub target: TargetSelection,
 890 }
 891
 892 impl Step for ErrorIndex {
 893     type Output = ();
 894     const DEFAULT: bool = true;
 895     const ONLY_HOSTS: bool = true;
 896
 897     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 898         let builder = run.builder;
 899         run.path("src/tools/error_index_generator").default_condition(builder.config.docs)
 900     }
 901
 902     fn make_run(run: RunConfig<'_>) {
 903         let target = run.target;
 904         run.builder.ensure(ErrorIndex { target });
 905     }
 906
 907     /// Generates the HTML rendered error-index by running the
 908     /// `error_index_generator` tool.
 909     fn run(self, builder: &Builder<'_>) {
 910         builder.info(&format!("Documenting error index ({})", self.target));
 911         let out = builder.doc_out(self.target);
 912         t!(fs::create_dir_all(&out));
 913         let mut index = tool::ErrorIndex::command(builder);
 914         index.arg("html");
 915         index.arg(out);
 916         index.arg(&builder.version);
 917
 918         builder.run(&mut index);
 919     }
 920 }
 921
 922 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 923 pub struct UnstableBookGen {
 924     target: TargetSelection,
 925 }
 926
 927 impl Step for UnstableBookGen {
 928     type Output = ();
 929     const DEFAULT: bool = true;
 930     const ONLY_HOSTS: bool = true;
 931
 932     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 933         let builder = run.builder;
 934         run.path("src/tools/unstable-book-gen").default_condition(builder.config.docs)
 935     }
 936
 937     fn make_run(run: RunConfig<'_>) {
 938         run.builder.ensure(UnstableBookGen { target: run.target });
 939     }
 940
 941     fn run(self, builder: &Builder<'_>) {
 942         let target = self.target;
 943
 944         builder.info(&format!("Generating unstable book md files ({})", target));
 945         let out = builder.md_doc_out(target).join("unstable-book");
 946         builder.create_dir(&out);
 947         builder.remove_dir(&out);
 948         let mut cmd = builder.tool_cmd(Tool::UnstableBookGen);
 949         cmd.arg(builder.src.join("library"));
 950         cmd.arg(builder.src.join("compiler"));
 951         cmd.arg(builder.src.join("src"));
 952         cmd.arg(out);
 953
 954         builder.run(&mut cmd);
 955     }
 956 }
 957
 958 fn symlink_dir_force(config: &Config, src: &Path, dst: &Path) -> io::Result<()> {
 959     if config.dry_run {
 960         return Ok(());
 961     }
 962     if let Ok(m) = fs::symlink_metadata(dst) {
 963         if m.file_type().is_dir() {
 964             fs::remove_dir_all(dst)?;
 965         } else {
 966             // handle directory junctions on windows by falling back to
 967             // `remove_dir`.
 968             fs::remove_file(dst).or_else(|_| fs::remove_dir(dst))?;
 969         }
 970     }
 971
 972     symlink_dir(config, src, dst)
 973 }
 974
 975 #[derive(Ord, PartialOrd, Debug, Copy, Clone, Hash, PartialEq, Eq)]
 976 pub struct RustcBook {
 977     pub compiler: Compiler,
 978     pub target: TargetSelection,
 979     pub validate: bool,
 980 }
 981
 982 impl Step for RustcBook {
 983     type Output = ();
 984     const DEFAULT: bool = true;
 985     const ONLY_HOSTS: bool = true;
 986
 987     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 988         let builder = run.builder;
 989         run.path("src/doc/rustc").default_condition(builder.config.docs)
 990     }
 991
 992     fn make_run(run: RunConfig<'_>) {
 993         run.builder.ensure(RustcBook {
 994             compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
 995             target: run.target,
 996             validate: false,
 997         });
 998     }
 999
1000     /// Builds the rustc book.
1001     ///
1002     /// The lints are auto-generated by a tool, and then merged into the book
1003     /// in the "md-doc" directory in the build output directory. Then
1004     /// "rustbook" is used to convert it to HTML.
1005     fn run(self, builder: &Builder<'_>) {
1006         let out_base = builder.md_doc_out(self.target).join("rustc");
1007         t!(fs::create_dir_all(&out_base));
1008         let out_listing = out_base.join("src/lints");
1009         builder.cp_r(&builder.src.join("src/doc/rustc"), &out_base);
1010         builder.info(&format!("Generating lint docs ({})", self.target));
1011
1012         let rustc = builder.rustc(self.compiler);
1013         // The tool runs `rustc` for extracting output examples, so it needs a
1014         // functional sysroot.
1015         builder.ensure(compile::Std::new(self.compiler, self.target));
1016         let mut cmd = builder.tool_cmd(Tool::LintDocs);
1017         cmd.arg("--src");
1018         cmd.arg(builder.src.join("compiler"));
1019         cmd.arg("--out");
1020         cmd.arg(&out_listing);
1021         cmd.arg("--rustc");
1022         cmd.arg(&rustc);
1023         cmd.arg("--rustc-target").arg(&self.target.rustc_target_arg());
1024         if builder.config.verbose() {
1025             cmd.arg("--verbose");
1026         }
1027         if self.validate {
1028             cmd.arg("--validate");
1029         }
1030         if !builder.unstable_features() {
1031             // We need to validate nightly features, even on the stable channel.
1032             cmd.env("RUSTC_BOOTSTRAP", "1");
1033         }
1034         // If the lib directories are in an unusual location (changed in
1035         // config.toml), then this needs to explicitly update the dylib search
1036         // path.
1037         builder.add_rustc_lib_path(self.compiler, &mut cmd);
1038         builder.run(&mut cmd);
1039         // Run rustbook/mdbook to generate the HTML pages.
1040         builder.ensure(RustbookSrc {
1041             target: self.target,
1042             name: INTERNER.intern_str("rustc"),
1043             src: INTERNER.intern_path(out_base),
1044         });
1045         if builder.was_invoked_explicitly::<Self>(Kind::Doc) {
1046             let out = builder.doc_out(self.target);
1047             let index = out.join("rustc").join("index.html");
1048             open(builder, &index);
1049         }
1050     }
1051 }