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