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