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;
  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: Interned<String>,
  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     RustcBook, "src/doc/rustc", "rustc";
  70     RustdocBook, "src/doc/rustdoc", "rustdoc";
  71 );
  72
  73 fn open(builder: &Builder<'_>, path: impl AsRef<Path>) {
  74     if builder.config.dry_run || !builder.config.cmd.open() {
  75         return;
  76     }
  77
  78     let path = path.as_ref();
  79     builder.info(&format!("Opening doc {}", path.display()));
  80     if let Err(err) = opener::open(path) {
  81         builder.info(&format!("{}\n", err));
  82     }
  83 }
  84
  85 // "src/libstd" -> ["src", "libstd"]
  86 //
  87 // Used for deciding whether a particular step is one requested by the user on
  88 // the `x.py doc` command line, which determines whether `--open` will open that
  89 // page.
  90 fn components_simplified(path: &PathBuf) -> Vec<&str> {
  91     path.iter().map(|component| component.to_str().unwrap_or("???")).collect()
  92 }
  93
  94 fn is_explicit_request(builder: &Builder<'_>, path: &str) -> bool {
  95     builder
  96         .paths
  97         .iter()
  98         .map(components_simplified)
  99         .any(|requested| requested.iter().copied().eq(path.split("/")))
 100 }
 101
 102 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 103 pub struct UnstableBook {
 104     target: Interned<String>,
 105 }
 106
 107 impl Step for UnstableBook {
 108     type Output = ();
 109     const DEFAULT: bool = true;
 110
 111     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 112         let builder = run.builder;
 113         run.path("src/doc/unstable-book").default_condition(builder.config.docs)
 114     }
 115
 116     fn make_run(run: RunConfig<'_>) {
 117         run.builder.ensure(UnstableBook { target: run.target });
 118     }
 119
 120     fn run(self, builder: &Builder<'_>) {
 121         builder.ensure(UnstableBookGen { target: self.target });
 122         builder.ensure(RustbookSrc {
 123             target: self.target,
 124             name: INTERNER.intern_str("unstable-book"),
 125             src: INTERNER.intern_path(builder.md_doc_out(self.target).join("unstable-book")),
 126         })
 127     }
 128 }
 129
 130 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 131 struct RustbookSrc {
 132     target: Interned<String>,
 133     name: Interned<String>,
 134     src: Interned<PathBuf>,
 135 }
 136
 137 impl Step for RustbookSrc {
 138     type Output = ();
 139
 140     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 141         run.never()
 142     }
 143
 144     /// Invoke `rustbook` for `target` for the doc book `name` from the `src` path.
 145     ///
 146     /// This will not actually generate any documentation if the documentation has
 147     /// already been generated.
 148     fn run(self, builder: &Builder<'_>) {
 149         let target = self.target;
 150         let name = self.name;
 151         let src = self.src;
 152         let out = builder.doc_out(target);
 153         t!(fs::create_dir_all(&out));
 154
 155         let out = out.join(name);
 156         let index = out.join("index.html");
 157         let rustbook = builder.tool_exe(Tool::Rustbook);
 158         let mut rustbook_cmd = builder.tool_cmd(Tool::Rustbook);
 159         if up_to_date(&src, &index) && up_to_date(&rustbook, &index) {
 160             return;
 161         }
 162         builder.info(&format!("Rustbook ({}) - {}", target, name));
 163         let _ = fs::remove_dir_all(&out);
 164
 165         builder.run(rustbook_cmd.arg("build").arg(&src).arg("-d").arg(out));
 166     }
 167 }
 168
 169 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 170 pub struct TheBook {
 171     compiler: Compiler,
 172     target: Interned<String>,
 173 }
 174
 175 impl Step for TheBook {
 176     type Output = ();
 177     const DEFAULT: bool = true;
 178
 179     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 180         let builder = run.builder;
 181         run.path("src/doc/book").default_condition(builder.config.docs)
 182     }
 183
 184     fn make_run(run: RunConfig<'_>) {
 185         run.builder.ensure(TheBook {
 186             compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
 187             target: run.target,
 188         });
 189     }
 190
 191     /// Builds the book and associated stuff.
 192     ///
 193     /// We need to build:
 194     ///
 195     /// * Book
 196     /// * Older edition redirects
 197     /// * Version info and CSS
 198     /// * Index page
 199     /// * Redirect pages
 200     fn run(self, builder: &Builder<'_>) {
 201         let compiler = self.compiler;
 202         let target = self.target;
 203
 204         // build book
 205         builder.ensure(RustbookSrc {
 206             target,
 207             name: INTERNER.intern_str("book"),
 208             src: INTERNER.intern_path(builder.src.join("src/doc/book")),
 209         });
 210
 211         // building older edition redirects
 212         for edition in &["first-edition", "second-edition", "2018-edition"] {
 213             builder.ensure(RustbookSrc {
 214                 target,
 215                 name: INTERNER.intern_string(format!("book/{}", edition)),
 216                 src: INTERNER.intern_path(builder.src.join("src/doc/book").join(edition)),
 217             });
 218         }
 219
 220         // build the version info page and CSS
 221         builder.ensure(Standalone { compiler, target });
 222
 223         // build the redirect pages
 224         builder.info(&format!("Documenting book redirect pages ({})", target));
 225         for file in t!(fs::read_dir(builder.src.join("src/doc/book/redirects"))) {
 226             let file = t!(file);
 227             let path = file.path();
 228             let path = path.to_str().unwrap();
 229
 230             invoke_rustdoc(builder, compiler, target, path);
 231         }
 232
 233         if is_explicit_request(builder, "src/doc/book") {
 234             let out = builder.doc_out(target);
 235             let index = out.join("book").join("index.html");
 236             open(builder, &index);
 237         }
 238     }
 239 }
 240
 241 fn invoke_rustdoc(
 242     builder: &Builder<'_>,
 243     compiler: Compiler,
 244     target: Interned<String>,
 245     markdown: &str,
 246 ) {
 247     let out = builder.doc_out(target);
 248
 249     let path = builder.src.join("src/doc").join(markdown);
 250
 251     let header = builder.src.join("src/doc/redirect.inc");
 252     let footer = builder.src.join("src/doc/footer.inc");
 253     let version_info = out.join("version_info.html");
 254
 255     let mut cmd = builder.rustdoc_cmd(compiler);
 256
 257     let out = out.join("book");
 258
 259     cmd.arg("--html-after-content")
 260         .arg(&footer)
 261         .arg("--html-before-content")
 262         .arg(&version_info)
 263         .arg("--html-in-header")
 264         .arg(&header)
 265         .arg("--markdown-no-toc")
 266         .arg("--markdown-playground-url")
 267         .arg("https://play.rust-lang.org/")
 268         .arg("-o")
 269         .arg(&out)
 270         .arg(&path)
 271         .arg("--markdown-css")
 272         .arg("../rust.css");
 273
 274     builder.run(&mut cmd);
 275 }
 276
 277 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 278 pub struct Standalone {
 279     compiler: Compiler,
 280     target: Interned<String>,
 281 }
 282
 283 impl Step for Standalone {
 284     type Output = ();
 285     const DEFAULT: bool = true;
 286
 287     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 288         let builder = run.builder;
 289         run.path("src/doc").default_condition(builder.config.docs)
 290     }
 291
 292     fn make_run(run: RunConfig<'_>) {
 293         run.builder.ensure(Standalone {
 294             compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
 295             target: run.target,
 296         });
 297     }
 298
 299     /// Generates all standalone documentation as compiled by the rustdoc in `stage`
 300     /// for the `target` into `out`.
 301     ///
 302     /// This will list all of `src/doc` looking for markdown files and appropriately
 303     /// perform transformations like substituting `VERSION`, `SHORT_HASH`, and
 304     /// `STAMP` along with providing the various header/footer HTML we've customized.
 305     ///
 306     /// In the end, this is just a glorified wrapper around rustdoc!
 307     fn run(self, builder: &Builder<'_>) {
 308         let target = self.target;
 309         let compiler = self.compiler;
 310         builder.info(&format!("Documenting standalone ({})", target));
 311         let out = builder.doc_out(target);
 312         t!(fs::create_dir_all(&out));
 313
 314         let favicon = builder.src.join("src/doc/favicon.inc");
 315         let footer = builder.src.join("src/doc/footer.inc");
 316         let full_toc = builder.src.join("src/doc/full-toc.inc");
 317         t!(fs::copy(builder.src.join("src/doc/rust.css"), out.join("rust.css")));
 318
 319         let version_input = builder.src.join("src/doc/version_info.html.template");
 320         let version_info = out.join("version_info.html");
 321
 322         if !builder.config.dry_run && !up_to_date(&version_input, &version_info) {
 323             let info = t!(fs::read_to_string(&version_input))
 324                 .replace("VERSION", &builder.rust_release())
 325                 .replace("SHORT_HASH", builder.rust_info.sha_short().unwrap_or(""))
 326                 .replace("STAMP", builder.rust_info.sha().unwrap_or(""));
 327             t!(fs::write(&version_info, &info));
 328         }
 329
 330         for file in t!(fs::read_dir(builder.src.join("src/doc"))) {
 331             let file = t!(file);
 332             let path = file.path();
 333             let filename = path.file_name().unwrap().to_str().unwrap();
 334             if !filename.ends_with(".md") || filename == "README.md" {
 335                 continue;
 336             }
 337
 338             let html = out.join(filename).with_extension("html");
 339             let rustdoc = builder.rustdoc(compiler);
 340             if up_to_date(&path, &html)
 341                 && up_to_date(&footer, &html)
 342                 && up_to_date(&favicon, &html)
 343                 && up_to_date(&full_toc, &html)
 344                 && (builder.config.dry_run || up_to_date(&version_info, &html))
 345                 && (builder.config.dry_run || up_to_date(&rustdoc, &html))
 346             {
 347                 continue;
 348             }
 349
 350             let mut cmd = builder.rustdoc_cmd(compiler);
 351             // Needed for --index-page flag
 352             cmd.arg("-Z").arg("unstable-options");
 353
 354             cmd.arg("--html-after-content")
 355                 .arg(&footer)
 356                 .arg("--html-before-content")
 357                 .arg(&version_info)
 358                 .arg("--html-in-header")
 359                 .arg(&favicon)
 360                 .arg("--markdown-no-toc")
 361                 .arg("--index-page")
 362                 .arg(&builder.src.join("src/doc/index.md"))
 363                 .arg("--markdown-playground-url")
 364                 .arg("https://play.rust-lang.org/")
 365                 .arg("-o")
 366                 .arg(&out)
 367                 .arg(&path);
 368
 369             if filename == "not_found.md" {
 370                 cmd.arg("--markdown-css").arg("https://doc.rust-lang.org/rust.css");
 371             } else {
 372                 cmd.arg("--markdown-css").arg("rust.css");
 373             }
 374             builder.run(&mut cmd);
 375         }
 376
 377         // We open doc/index.html as the default if invoked as `x.py doc --open`
 378         // with no particular explicit doc requested (e.g. src/libcore).
 379         if builder.paths.is_empty() || is_explicit_request(builder, "src/doc") {
 380             let index = out.join("index.html");
 381             open(builder, &index);
 382         }
 383     }
 384 }
 385
 386 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 387 pub struct Std {
 388     pub stage: u32,
 389     pub target: Interned<String>,
 390 }
 391
 392 impl Step for Std {
 393     type Output = ();
 394     const DEFAULT: bool = true;
 395
 396     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 397         let builder = run.builder;
 398         run.all_krates("test").default_condition(builder.config.docs)
 399     }
 400
 401     fn make_run(run: RunConfig<'_>) {
 402         run.builder.ensure(Std { stage: run.builder.top_stage, target: run.target });
 403     }
 404
 405     /// Compile all standard library documentation.
 406     ///
 407     /// This will generate all documentation for the standard library and its
 408     /// dependencies. This is largely just a wrapper around `cargo doc`.
 409     fn run(self, builder: &Builder<'_>) {
 410         let stage = self.stage;
 411         let target = self.target;
 412         builder.info(&format!("Documenting stage{} std ({})", stage, target));
 413         let out = builder.doc_out(target);
 414         t!(fs::create_dir_all(&out));
 415         let compiler = builder.compiler(stage, builder.config.build);
 416
 417         builder.ensure(compile::Std { compiler, target });
 418         let out_dir = builder.stage_out(compiler, Mode::Std).join(target).join("doc");
 419
 420         // Here what we're doing is creating a *symlink* (directory junction on
 421         // Windows) to the final output location. This is not done as an
 422         // optimization but rather for correctness. We've got three trees of
 423         // documentation, one for std, one for test, and one for rustc. It's then
 424         // our job to merge them all together.
 425         //
 426         // Unfortunately rustbuild doesn't know nearly as well how to merge doc
 427         // trees as rustdoc does itself, so instead of actually having three
 428         // separate trees we just have rustdoc output to the same location across
 429         // all of them.
 430         //
 431         // This way rustdoc generates output directly into the output, and rustdoc
 432         // will also directly handle merging.
 433         let my_out = builder.crate_doc_out(target);
 434         t!(symlink_dir_force(&builder.config, &my_out, &out_dir));
 435         t!(fs::copy(builder.src.join("src/doc/rust.css"), out.join("rust.css")));
 436
 437         let run_cargo_rustdoc_for = |package: &str| {
 438             let mut cargo =
 439                 builder.cargo(compiler, Mode::Std, SourceType::InTree, target, "rustdoc");
 440             compile::std_cargo(builder, target, compiler.stage, &mut cargo);
 441
 442             // Keep a whitelist so we do not build internal stdlib crates, these will be
 443             // build by the rustc step later if enabled.
 444             cargo.arg("-p").arg(package);
 445             // Create all crate output directories first to make sure rustdoc uses
 446             // relative links.
 447             // FIXME: Cargo should probably do this itself.
 448             t!(fs::create_dir_all(out_dir.join(package)));
 449             cargo
 450                 .arg("--")
 451                 .arg("--markdown-css")
 452                 .arg("rust.css")
 453                 .arg("--markdown-no-toc")
 454                 .arg("--generate-redirect-pages")
 455                 .arg("-Z")
 456                 .arg("unstable-options")
 457                 .arg("--resource-suffix")
 458                 .arg(crate::channel::CFG_RELEASE_NUM)
 459                 .arg("--index-page")
 460                 .arg(&builder.src.join("src/doc/index.md"));
 461
 462             builder.run(&mut cargo.into());
 463         };
 464         let krates = ["alloc", "core", "std", "proc_macro", "test"];
 465         for krate in &krates {
 466             run_cargo_rustdoc_for(krate);
 467         }
 468         builder.cp_r(&my_out, &out);
 469
 470         // Look for src/libstd, src/libcore etc in the `x.py doc` arguments and
 471         // open the corresponding rendered docs.
 472         for path in builder.paths.iter().map(components_simplified) {
 473             if path.get(0) == Some(&"src")
 474                 && path.get(1).map_or(false, |dir| dir.starts_with("lib"))
 475             {
 476                 let requested_crate = &path[1][3..];
 477                 if krates.contains(&requested_crate) {
 478                     let index = out.join(requested_crate).join("index.html");
 479                     open(builder, &index);
 480                 }
 481             }
 482         }
 483     }
 484 }
 485
 486 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 487 pub struct Rustc {
 488     stage: u32,
 489     target: Interned<String>,
 490 }
 491
 492 impl Step for Rustc {
 493     type Output = ();
 494     const DEFAULT: bool = true;
 495     const ONLY_HOSTS: bool = true;
 496
 497     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 498         let builder = run.builder;
 499         run.krate("rustc-main").default_condition(builder.config.docs)
 500     }
 501
 502     fn make_run(run: RunConfig<'_>) {
 503         run.builder.ensure(Rustc { stage: run.builder.top_stage, target: run.target });
 504     }
 505
 506     /// Generates compiler documentation.
 507     ///
 508     /// This will generate all documentation for compiler and dependencies.
 509     /// Compiler documentation is distributed separately, so we make sure
 510     /// we do not merge it with the other documentation from std, test and
 511     /// proc_macros. This is largely just a wrapper around `cargo doc`.
 512     fn run(self, builder: &Builder<'_>) {
 513         let stage = self.stage;
 514         let target = self.target;
 515         builder.info(&format!("Documenting stage{} compiler ({})", stage, target));
 516
 517         // This is the intended out directory for compiler documentation.
 518         let out = builder.compiler_doc_out(target);
 519         t!(fs::create_dir_all(&out));
 520
 521         // Get the correct compiler for this stage.
 522         let compiler = builder.compiler_for(stage, builder.config.build, target);
 523
 524         if !builder.config.compiler_docs {
 525             builder.info("\tskipping - compiler/librustdoc docs disabled");
 526             return;
 527         }
 528
 529         // Build rustc.
 530         builder.ensure(compile::Rustc { compiler, target });
 531
 532         // We do not symlink to the same shared folder that already contains std library
 533         // documentation from previous steps as we do not want to include that.
 534         let out_dir = builder.stage_out(compiler, Mode::Rustc).join(target).join("doc");
 535         t!(symlink_dir_force(&builder.config, &out, &out_dir));
 536
 537         // Build cargo command.
 538         let mut cargo = builder.cargo(compiler, Mode::Rustc, SourceType::InTree, target, "doc");
 539         cargo.env(
 540             "RUSTDOCFLAGS",
 541             "--document-private-items \
 542             --enable-index-page -Zunstable-options",
 543         );
 544         compile::rustc_cargo(builder, &mut cargo, target);
 545
 546         // Only include compiler crates, no dependencies of those, such as `libc`.
 547         cargo.arg("--no-deps");
 548
 549         // Find dependencies for top level crates.
 550         let mut compiler_crates = HashSet::new();
 551         for root_crate in &["rustc_driver", "rustc_codegen_llvm", "rustc_codegen_ssa"] {
 552             compiler_crates
 553                 .extend(builder.in_tree_crates(root_crate).into_iter().map(|krate| krate.name));
 554         }
 555
 556         for krate in &compiler_crates {
 557             // Create all crate output directories first to make sure rustdoc uses
 558             // relative links.
 559             // FIXME: Cargo should probably do this itself.
 560             t!(fs::create_dir_all(out_dir.join(krate)));
 561             cargo.arg("-p").arg(krate);
 562         }
 563
 564         builder.run(&mut cargo.into());
 565     }
 566 }
 567
 568 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 569 pub struct Rustdoc {
 570     stage: u32,
 571     target: Interned<String>,
 572 }
 573
 574 impl Step for Rustdoc {
 575     type Output = ();
 576     const DEFAULT: bool = true;
 577     const ONLY_HOSTS: bool = true;
 578
 579     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 580         run.krate("rustdoc-tool")
 581     }
 582
 583     fn make_run(run: RunConfig<'_>) {
 584         run.builder.ensure(Rustdoc { stage: run.builder.top_stage, target: run.target });
 585     }
 586
 587     /// Generates compiler documentation.
 588     ///
 589     /// This will generate all documentation for compiler and dependencies.
 590     /// Compiler documentation is distributed separately, so we make sure
 591     /// we do not merge it with the other documentation from std, test and
 592     /// proc_macros. This is largely just a wrapper around `cargo doc`.
 593     fn run(self, builder: &Builder<'_>) {
 594         let stage = self.stage;
 595         let target = self.target;
 596         builder.info(&format!("Documenting stage{} rustdoc ({})", stage, target));
 597
 598         // This is the intended out directory for compiler documentation.
 599         let out = builder.compiler_doc_out(target);
 600         t!(fs::create_dir_all(&out));
 601
 602         // Get the correct compiler for this stage.
 603         let compiler = builder.compiler_for(stage, builder.config.build, target);
 604
 605         if !builder.config.compiler_docs {
 606             builder.info("\tskipping - compiler/librustdoc docs disabled");
 607             return;
 608         }
 609
 610         // Build rustc docs so that we generate relative links.
 611         builder.ensure(Rustc { stage, target });
 612
 613         // Build rustdoc.
 614         builder.ensure(tool::Rustdoc { compiler });
 615
 616         // Symlink compiler docs to the output directory of rustdoc documentation.
 617         let out_dir = builder.stage_out(compiler, Mode::ToolRustc).join(target).join("doc");
 618         t!(fs::create_dir_all(&out_dir));
 619         t!(symlink_dir_force(&builder.config, &out, &out_dir));
 620
 621         // Build cargo command.
 622         let mut cargo = prepare_tool_cargo(
 623             builder,
 624             compiler,
 625             Mode::ToolRustc,
 626             target,
 627             "doc",
 628             "src/tools/rustdoc",
 629             SourceType::InTree,
 630             &[],
 631         );
 632
 633         // Only include compiler crates, no dependencies of those, such as `libc`.
 634         cargo.arg("--no-deps");
 635         cargo.arg("-p").arg("rustdoc");
 636
 637         cargo.env("RUSTDOCFLAGS", "--document-private-items");
 638         builder.run(&mut cargo.into());
 639     }
 640 }
 641
 642 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 643 pub struct ErrorIndex {
 644     target: Interned<String>,
 645 }
 646
 647 impl Step for ErrorIndex {
 648     type Output = ();
 649     const DEFAULT: bool = true;
 650     const ONLY_HOSTS: bool = true;
 651
 652     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 653         let builder = run.builder;
 654         run.path("src/tools/error_index_generator").default_condition(builder.config.docs)
 655     }
 656
 657     fn make_run(run: RunConfig<'_>) {
 658         run.builder.ensure(ErrorIndex { target: run.target });
 659     }
 660
 661     /// Generates the HTML rendered error-index by running the
 662     /// `error_index_generator` tool.
 663     fn run(self, builder: &Builder<'_>) {
 664         let target = self.target;
 665
 666         builder.info(&format!("Documenting error index ({})", target));
 667         let out = builder.doc_out(target);
 668         t!(fs::create_dir_all(&out));
 669         let compiler = builder.compiler(2, builder.config.build);
 670         let mut index = tool::ErrorIndex::command(builder, compiler);
 671         index.arg("html");
 672         index.arg(out.join("error-index.html"));
 673         index.arg(crate::channel::CFG_RELEASE_NUM);
 674
 675         // FIXME: shouldn't have to pass this env var
 676         index.env("CFG_BUILD", &builder.config.build);
 677
 678         builder.run(&mut index);
 679     }
 680 }
 681
 682 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 683 pub struct UnstableBookGen {
 684     target: Interned<String>,
 685 }
 686
 687 impl Step for UnstableBookGen {
 688     type Output = ();
 689     const DEFAULT: bool = true;
 690     const ONLY_HOSTS: bool = true;
 691
 692     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 693         let builder = run.builder;
 694         run.path("src/tools/unstable-book-gen").default_condition(builder.config.docs)
 695     }
 696
 697     fn make_run(run: RunConfig<'_>) {
 698         run.builder.ensure(UnstableBookGen { target: run.target });
 699     }
 700
 701     fn run(self, builder: &Builder<'_>) {
 702         let target = self.target;
 703
 704         builder.info(&format!("Generating unstable book md files ({})", target));
 705         let out = builder.md_doc_out(target).join("unstable-book");
 706         builder.create_dir(&out);
 707         builder.remove_dir(&out);
 708         let mut cmd = builder.tool_cmd(Tool::UnstableBookGen);
 709         cmd.arg(builder.src.join("src"));
 710         cmd.arg(out);
 711
 712         builder.run(&mut cmd);
 713     }
 714 }
 715
 716 fn symlink_dir_force(config: &Config, src: &Path, dst: &Path) -> io::Result<()> {
 717     if config.dry_run {
 718         return Ok(());
 719     }
 720     if let Ok(m) = fs::symlink_metadata(dst) {
 721         if m.file_type().is_dir() {
 722             fs::remove_dir_all(dst)?;
 723         } else {
 724             // handle directory junctions on windows by falling back to
 725             // `remove_dir`.
 726             fs::remove_file(dst).or_else(|_| fs::remove_dir(dst))?;
 727         }
 728     }
 729
 730     symlink_dir(config, src, dst)
 731 }