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::{PathBuf, Path};
  14
  15 use crate::Mode;
  16 use build_helper::up_to_date;
  17
  18 use crate::util::symlink_dir;
  19 use crate::builder::{Builder, Compiler, RunConfig, ShouldRun, Step};
  20 use crate::tool::{self, prepare_tool_cargo, Tool, SourceType};
  21 use crate::compile;
  22 use crate::cache::{INTERNER, Interned};
  23 use crate::config::Config;
  24
  25 macro_rules! book {
  26     ($($name:ident, $path:expr, $book_name:expr, $book_ver: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(Rustbook {
  50                     target: self.target,
  51                     name: INTERNER.intern_str($book_name),
  52                     version: $book_ver,
  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", RustbookVersion::MdBook2;
  64     EmbeddedBook, "src/doc/embedded-book", "embedded-book", RustbookVersion::MdBook2;
  65     Nomicon, "src/doc/nomicon", "nomicon", RustbookVersion::MdBook1;
  66     Reference, "src/doc/reference", "reference", RustbookVersion::MdBook1;
  67     RustByExample, "src/doc/rust-by-example", "rust-by-example", RustbookVersion::MdBook1;
  68     RustcBook, "src/doc/rustc", "rustc", RustbookVersion::MdBook1;
  69     RustdocBook, "src/doc/rustdoc", "rustdoc", RustbookVersion::MdBook1;
  70 );
  71
  72 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
  73 enum RustbookVersion {
  74     MdBook1,
  75     MdBook2,
  76 }
  77
  78 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
  79 struct Rustbook {
  80     target: Interned<String>,
  81     name: Interned<String>,
  82     version: RustbookVersion,
  83 }
  84
  85 impl Step for Rustbook {
  86     type Output = ();
  87
  88     // rustbook is never directly called, and only serves as a shim for the nomicon and the
  89     // reference.
  90     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
  91         run.never()
  92     }
  93
  94     /// Invoke `rustbook` for `target` for the doc book `name`.
  95     ///
  96     /// This will not actually generate any documentation if the documentation has
  97     /// already been generated.
  98     fn run(self, builder: &Builder<'_>) {
  99         let src = builder.src.join("src/doc");
 100         builder.ensure(RustbookSrc {
 101             target: self.target,
 102             name: self.name,
 103             src: INTERNER.intern_path(src),
 104             version: self.version,
 105         });
 106     }
 107 }
 108
 109 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 110 pub struct UnstableBook {
 111     target: Interned<String>,
 112 }
 113
 114 impl Step for UnstableBook {
 115     type Output = ();
 116     const DEFAULT: bool = true;
 117
 118     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 119         let builder = run.builder;
 120         run.path("src/doc/unstable-book").default_condition(builder.config.docs)
 121     }
 122
 123     fn make_run(run: RunConfig<'_>) {
 124         run.builder.ensure(UnstableBook {
 125             target: run.target,
 126         });
 127     }
 128
 129     fn run(self, builder: &Builder<'_>) {
 130         builder.ensure(UnstableBookGen {
 131             target: self.target,
 132         });
 133         builder.ensure(RustbookSrc {
 134             target: self.target,
 135             name: INTERNER.intern_str("unstable-book"),
 136             src: builder.md_doc_out(self.target),
 137             version: RustbookVersion::MdBook1,
 138         })
 139     }
 140 }
 141
 142 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 143 pub struct CargoBook {
 144     target: Interned<String>,
 145     name: Interned<String>,
 146 }
 147
 148 impl Step for CargoBook {
 149     type Output = ();
 150     const DEFAULT: bool = true;
 151
 152     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 153         let builder = run.builder;
 154         run.path("src/tools/cargo/src/doc/book").default_condition(builder.config.docs)
 155     }
 156
 157     fn make_run(run: RunConfig<'_>) {
 158         run.builder.ensure(CargoBook {
 159             target: run.target,
 160             name: INTERNER.intern_str("cargo"),
 161         });
 162     }
 163
 164     fn run(self, builder: &Builder<'_>) {
 165         let target = self.target;
 166         let name = self.name;
 167         let src = builder.src.join("src/tools/cargo/src/doc");
 168
 169         let out = builder.doc_out(target);
 170         t!(fs::create_dir_all(&out));
 171
 172         let out = out.join(name);
 173
 174         builder.info(&format!("Cargo Book ({}) - {}", target, name));
 175
 176         let _ = fs::remove_dir_all(&out);
 177
 178         builder.run(builder.tool_cmd(Tool::Rustbook)
 179                        .arg("build")
 180                        .arg(&src)
 181                        .arg("-d")
 182                        .arg(out));
 183     }
 184 }
 185
 186 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 187 struct RustbookSrc {
 188     target: Interned<String>,
 189     name: Interned<String>,
 190     src: Interned<PathBuf>,
 191     version: RustbookVersion,
 192 }
 193
 194 impl Step for RustbookSrc {
 195     type Output = ();
 196
 197     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 198         run.never()
 199     }
 200
 201     /// Invoke `rustbook` for `target` for the doc book `name` from the `src` path.
 202     ///
 203     /// This will not actually generate any documentation if the documentation has
 204     /// already been generated.
 205     fn run(self, builder: &Builder<'_>) {
 206         let target = self.target;
 207         let name = self.name;
 208         let src = self.src;
 209         let out = builder.doc_out(target);
 210         t!(fs::create_dir_all(&out));
 211
 212         let out = out.join(name);
 213         let src = src.join(name);
 214         let index = out.join("index.html");
 215         let rustbook = builder.tool_exe(Tool::Rustbook);
 216         let mut rustbook_cmd = builder.tool_cmd(Tool::Rustbook);
 217         if up_to_date(&src, &index) && up_to_date(&rustbook, &index) {
 218             return
 219         }
 220         builder.info(&format!("Rustbook ({}) - {}", target, name));
 221         let _ = fs::remove_dir_all(&out);
 222
 223         let vers = match self.version {
 224             RustbookVersion::MdBook1 => "1",
 225             RustbookVersion::MdBook2 => "2",
 226         };
 227
 228         builder.run(rustbook_cmd
 229                        .arg("build")
 230                        .arg(&src)
 231                        .arg("-d")
 232                        .arg(out)
 233                        .arg("-m")
 234                        .arg(vers));
 235     }
 236 }
 237
 238 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 239 pub struct TheBook {
 240     compiler: Compiler,
 241     target: Interned<String>,
 242     name: &'static str,
 243 }
 244
 245 impl Step for TheBook {
 246     type Output = ();
 247     const DEFAULT: bool = true;
 248
 249     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 250         let builder = run.builder;
 251         run.path("src/doc/book").default_condition(builder.config.docs)
 252     }
 253
 254     fn make_run(run: RunConfig<'_>) {
 255         run.builder.ensure(TheBook {
 256             compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
 257             target: run.target,
 258             name: "book",
 259         });
 260     }
 261
 262     /// Builds the book and associated stuff.
 263     ///
 264     /// We need to build:
 265     ///
 266     /// * Book (first edition)
 267     /// * Book (second edition)
 268     /// * Version info and CSS
 269     /// * Index page
 270     /// * Redirect pages
 271     fn run(self, builder: &Builder<'_>) {
 272         let compiler = self.compiler;
 273         let target = self.target;
 274         let name = self.name;
 275
 276         // build book
 277         builder.ensure(Rustbook {
 278             target,
 279             name: INTERNER.intern_string(name.to_string()),
 280             version: RustbookVersion::MdBook1,
 281         });
 282
 283         // building older edition redirects
 284
 285         let source_name = format!("{}/first-edition", name);
 286         builder.ensure(Rustbook {
 287             target,
 288             name: INTERNER.intern_string(source_name),
 289             version: RustbookVersion::MdBook1,
 290         });
 291
 292         let source_name = format!("{}/second-edition", name);
 293         builder.ensure(Rustbook {
 294             target,
 295             name: INTERNER.intern_string(source_name),
 296             version: RustbookVersion::MdBook1,
 297         });
 298
 299         let source_name = format!("{}/2018-edition", name);
 300         builder.ensure(Rustbook {
 301             target,
 302             name: INTERNER.intern_string(source_name),
 303             version: RustbookVersion::MdBook1,
 304         });
 305
 306         // build the version info page and CSS
 307         builder.ensure(Standalone {
 308             compiler,
 309             target,
 310         });
 311
 312         // build the redirect pages
 313         builder.info(&format!("Documenting book redirect pages ({})", target));
 314         for file in t!(fs::read_dir(builder.src.join("src/doc/book/redirects"))) {
 315             let file = t!(file);
 316             let path = file.path();
 317             let path = path.to_str().unwrap();
 318
 319             invoke_rustdoc(builder, compiler, target, path);
 320         }
 321     }
 322 }
 323
 324 fn invoke_rustdoc(
 325     builder: &Builder<'_>,
 326     compiler: Compiler,
 327     target: Interned<String>,
 328     markdown: &str,
 329 ) {
 330     let out = builder.doc_out(target);
 331
 332     let path = builder.src.join("src/doc").join(markdown);
 333
 334     let favicon = builder.src.join("src/doc/favicon.inc");
 335     let footer = builder.src.join("src/doc/footer.inc");
 336     let version_info = out.join("version_info.html");
 337
 338     let mut cmd = builder.rustdoc_cmd(compiler);
 339
 340     let out = out.join("book");
 341
 342     cmd.arg("--html-after-content").arg(&footer)
 343         .arg("--html-before-content").arg(&version_info)
 344         .arg("--html-in-header").arg(&favicon)
 345         .arg("--markdown-no-toc")
 346         .arg("--resource-suffix").arg(crate::channel::CFG_RELEASE_NUM)
 347         .arg("--markdown-playground-url").arg("https://play.rust-lang.org/")
 348         .arg("-o").arg(&out).arg(&path)
 349         .arg("--markdown-css").arg("../rust.css");
 350
 351     builder.run(&mut cmd);
 352 }
 353
 354 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 355 pub struct Standalone {
 356     compiler: Compiler,
 357     target: Interned<String>,
 358 }
 359
 360 impl Step for Standalone {
 361     type Output = ();
 362     const DEFAULT: bool = true;
 363
 364     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 365         let builder = run.builder;
 366         run.path("src/doc").default_condition(builder.config.docs)
 367     }
 368
 369     fn make_run(run: RunConfig<'_>) {
 370         run.builder.ensure(Standalone {
 371             compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
 372             target: run.target,
 373         });
 374     }
 375
 376     /// Generates all standalone documentation as compiled by the rustdoc in `stage`
 377     /// for the `target` into `out`.
 378     ///
 379     /// This will list all of `src/doc` looking for markdown files and appropriately
 380     /// perform transformations like substituting `VERSION`, `SHORT_HASH`, and
 381     /// `STAMP` along with providing the various header/footer HTML we've customized.
 382     ///
 383     /// In the end, this is just a glorified wrapper around rustdoc!
 384     fn run(self, builder: &Builder<'_>) {
 385         let target = self.target;
 386         let compiler = self.compiler;
 387         builder.info(&format!("Documenting standalone ({})", target));
 388         let out = builder.doc_out(target);
 389         t!(fs::create_dir_all(&out));
 390
 391         let favicon = builder.src.join("src/doc/favicon.inc");
 392         let footer = builder.src.join("src/doc/footer.inc");
 393         let full_toc = builder.src.join("src/doc/full-toc.inc");
 394         t!(fs::copy(builder.src.join("src/doc/rust.css"), out.join("rust.css")));
 395
 396         let version_input = builder.src.join("src/doc/version_info.html.template");
 397         let version_info = out.join("version_info.html");
 398
 399         if !builder.config.dry_run && !up_to_date(&version_input, &version_info) {
 400             let info = t!(fs::read_to_string(&version_input))
 401                 .replace("VERSION", &builder.rust_release())
 402                 .replace("SHORT_HASH", builder.rust_info.sha_short().unwrap_or(""))
 403                 .replace("STAMP", builder.rust_info.sha().unwrap_or(""));
 404             t!(fs::write(&version_info, &info));
 405         }
 406
 407         for file in t!(fs::read_dir(builder.src.join("src/doc"))) {
 408             let file = t!(file);
 409             let path = file.path();
 410             let filename = path.file_name().unwrap().to_str().unwrap();
 411             if !filename.ends_with(".md") || filename == "README.md" {
 412                 continue
 413             }
 414
 415             let html = out.join(filename).with_extension("html");
 416             let rustdoc = builder.rustdoc(compiler);
 417             if up_to_date(&path, &html) &&
 418                up_to_date(&footer, &html) &&
 419                up_to_date(&favicon, &html) &&
 420                up_to_date(&full_toc, &html) &&
 421                up_to_date(&version_info, &html) &&
 422                (builder.config.dry_run || up_to_date(&rustdoc, &html)) {
 423                 continue
 424             }
 425
 426             let mut cmd = builder.rustdoc_cmd(compiler);
 427             cmd.arg("--html-after-content").arg(&footer)
 428                .arg("--html-before-content").arg(&version_info)
 429                .arg("--html-in-header").arg(&favicon)
 430                .arg("--markdown-no-toc")
 431                .arg("--resource-suffix").arg(crate::channel::CFG_RELEASE_NUM)
 432                .arg("--index-page").arg(&builder.src.join("src/doc/index.md"))
 433                .arg("--markdown-playground-url").arg("https://play.rust-lang.org/")
 434                .arg("-o").arg(&out)
 435                .arg(&path);
 436
 437             if filename == "not_found.md" {
 438                 cmd.arg("--markdown-css")
 439                    .arg("https://doc.rust-lang.org/rust.css");
 440             } else {
 441                 cmd.arg("--markdown-css").arg("rust.css");
 442             }
 443             builder.run(&mut cmd);
 444         }
 445     }
 446 }
 447
 448 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 449 pub struct Std {
 450     pub stage: u32,
 451     pub target: Interned<String>,
 452 }
 453
 454 impl Step for Std {
 455     type Output = ();
 456     const DEFAULT: bool = true;
 457
 458     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 459         let builder = run.builder;
 460         run.all_krates("std").default_condition(builder.config.docs)
 461     }
 462
 463     fn make_run(run: RunConfig<'_>) {
 464         run.builder.ensure(Std {
 465             stage: run.builder.top_stage,
 466             target: run.target
 467         });
 468     }
 469
 470     /// Compile all standard library documentation.
 471     ///
 472     /// This will generate all documentation for the standard library and its
 473     /// dependencies. This is largely just a wrapper around `cargo doc`.
 474     fn run(self, builder: &Builder<'_>) {
 475         let stage = self.stage;
 476         let target = self.target;
 477         builder.info(&format!("Documenting stage{} std ({})", stage, target));
 478         let out = builder.doc_out(target);
 479         t!(fs::create_dir_all(&out));
 480         let compiler = builder.compiler(stage, builder.config.build);
 481         let compiler = if builder.force_use_stage1(compiler, target) {
 482             builder.compiler(1, compiler.host)
 483         } else {
 484             compiler
 485         };
 486
 487         builder.ensure(compile::Std { compiler, target });
 488         let out_dir = builder.stage_out(compiler, Mode::Std)
 489                            .join(target).join("doc");
 490
 491         // Here what we're doing is creating a *symlink* (directory junction on
 492         // Windows) to the final output location. This is not done as an
 493         // optimization but rather for correctness. We've got three trees of
 494         // documentation, one for std, one for test, and one for rustc. It's then
 495         // our job to merge them all together.
 496         //
 497         // Unfortunately rustbuild doesn't know nearly as well how to merge doc
 498         // trees as rustdoc does itself, so instead of actually having three
 499         // separate trees we just have rustdoc output to the same location across
 500         // all of them.
 501         //
 502         // This way rustdoc generates output directly into the output, and rustdoc
 503         // will also directly handle merging.
 504         let my_out = builder.crate_doc_out(target);
 505         t!(symlink_dir_force(&builder.config, &my_out, &out_dir));
 506         t!(fs::copy(builder.src.join("src/doc/rust.css"), out.join("rust.css")));
 507
 508         let run_cargo_rustdoc_for = |package: &str| {
 509             let mut cargo = builder.cargo(compiler, Mode::Std, target, "rustdoc");
 510             compile::std_cargo(builder, &compiler, target, &mut cargo);
 511
 512             // Keep a whitelist so we do not build internal stdlib crates, these will be
 513             // build by the rustc step later if enabled.
 514             cargo.arg("-Z").arg("unstable-options")
 515                  .arg("-p").arg(package);
 516             // Create all crate output directories first to make sure rustdoc uses
 517             // relative links.
 518             // FIXME: Cargo should probably do this itself.
 519             t!(fs::create_dir_all(out_dir.join(package)));
 520             cargo.arg("--")
 521                  .arg("--markdown-css").arg("rust.css")
 522                  .arg("--markdown-no-toc")
 523                  .arg("--generate-redirect-pages")
 524                  .arg("--resource-suffix").arg(crate::channel::CFG_RELEASE_NUM)
 525                  .arg("--index-page").arg(&builder.src.join("src/doc/index.md"));
 526
 527             builder.run(&mut cargo);
 528             builder.cp_r(&my_out, &out);
 529         };
 530         for krate in &["alloc", "core", "std"] {
 531             run_cargo_rustdoc_for(krate);
 532         }
 533     }
 534 }
 535
 536 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 537 pub struct Test {
 538     stage: u32,
 539     target: Interned<String>,
 540 }
 541
 542 impl Step for Test {
 543     type Output = ();
 544     const DEFAULT: bool = true;
 545
 546     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 547         let builder = run.builder;
 548         run.krate("test").default_condition(builder.config.docs)
 549     }
 550
 551     fn make_run(run: RunConfig<'_>) {
 552         run.builder.ensure(Test {
 553             stage: run.builder.top_stage,
 554             target: run.target,
 555         });
 556     }
 557
 558     /// Compile all libtest documentation.
 559     ///
 560     /// This will generate all documentation for libtest and its dependencies. This
 561     /// is largely just a wrapper around `cargo doc`.
 562     fn run(self, builder: &Builder<'_>) {
 563         let stage = self.stage;
 564         let target = self.target;
 565         builder.info(&format!("Documenting stage{} test ({})", stage, target));
 566         let out = builder.doc_out(target);
 567         t!(fs::create_dir_all(&out));
 568         let compiler = builder.compiler(stage, builder.config.build);
 569         let compiler = if builder.force_use_stage1(compiler, target) {
 570             builder.compiler(1, compiler.host)
 571         } else {
 572             compiler
 573         };
 574
 575         // Build libstd docs so that we generate relative links
 576         builder.ensure(Std { stage, target });
 577
 578         builder.ensure(compile::Test { compiler, target });
 579         let out_dir = builder.stage_out(compiler, Mode::Test)
 580                            .join(target).join("doc");
 581
 582         // See docs in std above for why we symlink
 583         let my_out = builder.crate_doc_out(target);
 584         t!(symlink_dir_force(&builder.config, &my_out, &out_dir));
 585
 586         let mut cargo = builder.cargo(compiler, Mode::Test, target, "doc");
 587         compile::test_cargo(builder, &compiler, target, &mut cargo);
 588
 589         cargo.arg("--no-deps")
 590              .arg("-p").arg("test")
 591              .env("RUSTDOC_GENERATE_REDIRECT_PAGES", "1");
 592
 593         builder.run(&mut cargo);
 594         builder.cp_r(&my_out, &out);
 595     }
 596 }
 597
 598 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 599 pub struct WhitelistedRustc {
 600     stage: u32,
 601     target: Interned<String>,
 602 }
 603
 604 impl Step for WhitelistedRustc {
 605     type Output = ();
 606     const DEFAULT: bool = true;
 607     const ONLY_HOSTS: bool = true;
 608
 609     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 610         let builder = run.builder;
 611         run.krate("rustc-main").default_condition(builder.config.docs)
 612     }
 613
 614     fn make_run(run: RunConfig<'_>) {
 615         run.builder.ensure(WhitelistedRustc {
 616             stage: run.builder.top_stage,
 617             target: run.target,
 618         });
 619     }
 620
 621     /// Generates whitelisted compiler crate documentation.
 622     ///
 623     /// This will generate all documentation for crates that are whitelisted
 624     /// to be included in the standard documentation. This documentation is
 625     /// included in the standard Rust documentation, so we should always
 626     /// document it and symlink to merge with the rest of the std and test
 627     /// documentation. We don't build other compiler documentation
 628     /// here as we want to be able to keep it separate from the standard
 629     /// documentation. This is largely just a wrapper around `cargo doc`.
 630     fn run(self, builder: &Builder<'_>) {
 631         let stage = self.stage;
 632         let target = self.target;
 633         builder.info(&format!("Documenting stage{} whitelisted compiler ({})", stage, target));
 634         let out = builder.doc_out(target);
 635         t!(fs::create_dir_all(&out));
 636         let compiler = builder.compiler(stage, builder.config.build);
 637         let compiler = if builder.force_use_stage1(compiler, target) {
 638             builder.compiler(1, compiler.host)
 639         } else {
 640             compiler
 641         };
 642
 643         // Build libstd docs so that we generate relative links
 644         builder.ensure(Std { stage, target });
 645
 646         builder.ensure(compile::Rustc { compiler, target });
 647         let out_dir = builder.stage_out(compiler, Mode::Rustc)
 648                            .join(target).join("doc");
 649
 650         // See docs in std above for why we symlink
 651         let my_out = builder.crate_doc_out(target);
 652         t!(symlink_dir_force(&builder.config, &my_out, &out_dir));
 653
 654         let mut cargo = builder.cargo(compiler, Mode::Rustc, target, "doc");
 655         compile::rustc_cargo(builder, &mut cargo);
 656
 657         // We don't want to build docs for internal compiler dependencies in this
 658         // step (there is another step for that). Therefore, we whitelist the crates
 659         // for which docs must be built.
 660         for krate in &["proc_macro"] {
 661             cargo.arg("-p").arg(krate)
 662                  .env("RUSTDOC_GENERATE_REDIRECT_PAGES", "1");
 663         }
 664
 665         builder.run(&mut cargo);
 666         builder.cp_r(&my_out, &out);
 667     }
 668 }
 669
 670 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 671 pub struct Rustc {
 672     stage: u32,
 673     target: Interned<String>,
 674 }
 675
 676 impl Step for Rustc {
 677     type Output = ();
 678     const DEFAULT: bool = true;
 679     const ONLY_HOSTS: bool = true;
 680
 681     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 682         let builder = run.builder;
 683         run.krate("rustc-main").default_condition(builder.config.docs)
 684     }
 685
 686     fn make_run(run: RunConfig<'_>) {
 687         run.builder.ensure(Rustc {
 688             stage: run.builder.top_stage,
 689             target: run.target,
 690         });
 691     }
 692
 693     /// Generates compiler documentation.
 694     ///
 695     /// This will generate all documentation for compiler and dependencies.
 696     /// Compiler documentation is distributed separately, so we make sure
 697     /// we do not merge it with the other documentation from std, test and
 698     /// proc_macros. This is largely just a wrapper around `cargo doc`.
 699     fn run(self, builder: &Builder<'_>) {
 700         let stage = self.stage;
 701         let target = self.target;
 702         builder.info(&format!("Documenting stage{} compiler ({})", stage, target));
 703
 704         // This is the intended out directory for compiler documentation.
 705         let out = builder.compiler_doc_out(target);
 706         t!(fs::create_dir_all(&out));
 707
 708         // Get the correct compiler for this stage.
 709         let compiler = builder.compiler(stage, builder.config.build);
 710         let compiler = if builder.force_use_stage1(compiler, target) {
 711             builder.compiler(1, compiler.host)
 712         } else {
 713             compiler
 714         };
 715
 716         if !builder.config.compiler_docs {
 717             builder.info("\tskipping - compiler/librustdoc docs disabled");
 718             return;
 719         }
 720
 721         // Build rustc.
 722         builder.ensure(compile::Rustc { compiler, target });
 723
 724         // We do not symlink to the same shared folder that already contains std library
 725         // documentation from previous steps as we do not want to include that.
 726         let out_dir = builder.stage_out(compiler, Mode::Rustc).join(target).join("doc");
 727         t!(symlink_dir_force(&builder.config, &out, &out_dir));
 728
 729         // Build cargo command.
 730         let mut cargo = builder.cargo(compiler, Mode::Rustc, target, "doc");
 731         cargo.env("RUSTDOCFLAGS", "--document-private-items");
 732         compile::rustc_cargo(builder, &mut cargo);
 733
 734         // Only include compiler crates, no dependencies of those, such as `libc`.
 735         cargo.arg("--no-deps");
 736
 737         // Find dependencies for top level crates.
 738         let mut compiler_crates = HashSet::new();
 739         for root_crate in &["rustc_driver", "rustc_codegen_llvm", "rustc_codegen_ssa"] {
 740             let interned_root_crate = INTERNER.intern_str(root_crate);
 741             find_compiler_crates(builder, &interned_root_crate, &mut compiler_crates);
 742         }
 743
 744         for krate in &compiler_crates {
 745             // Create all crate output directories first to make sure rustdoc uses
 746             // relative links.
 747             // FIXME: Cargo should probably do this itself.
 748             t!(fs::create_dir_all(out_dir.join(krate)));
 749             cargo.arg("-p").arg(krate);
 750         }
 751
 752         builder.run(&mut cargo);
 753     }
 754 }
 755
 756 fn find_compiler_crates(
 757     builder: &Builder<'_>,
 758     name: &Interned<String>,
 759     crates: &mut HashSet<Interned<String>>
 760 ) {
 761     // Add current crate.
 762     crates.insert(*name);
 763
 764     // Look for dependencies.
 765     for dep in builder.crates.get(name).unwrap().deps.iter() {
 766         if builder.crates.get(dep).unwrap().is_local(builder) {
 767             find_compiler_crates(builder, dep, crates);
 768         }
 769     }
 770 }
 771
 772 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 773 pub struct Rustdoc {
 774     stage: u32,
 775     target: Interned<String>,
 776 }
 777
 778 impl Step for Rustdoc {
 779     type Output = ();
 780     const DEFAULT: bool = true;
 781     const ONLY_HOSTS: bool = true;
 782
 783     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 784         run.krate("rustdoc-tool")
 785     }
 786
 787     fn make_run(run: RunConfig<'_>) {
 788         run.builder.ensure(Rustdoc {
 789             stage: run.builder.top_stage,
 790             target: run.target,
 791         });
 792     }
 793
 794     /// Generates compiler documentation.
 795     ///
 796     /// This will generate all documentation for compiler and dependencies.
 797     /// Compiler documentation is distributed separately, so we make sure
 798     /// we do not merge it with the other documentation from std, test and
 799     /// proc_macros. This is largely just a wrapper around `cargo doc`.
 800     fn run(self, builder: &Builder<'_>) {
 801         let stage = self.stage;
 802         let target = self.target;
 803         builder.info(&format!("Documenting stage{} rustdoc ({})", stage, target));
 804
 805         // This is the intended out directory for compiler documentation.
 806         let out = builder.compiler_doc_out(target);
 807         t!(fs::create_dir_all(&out));
 808
 809         // Get the correct compiler for this stage.
 810         let compiler = builder.compiler(stage, builder.config.build);
 811         let compiler = if builder.force_use_stage1(compiler, target) {
 812             builder.compiler(1, compiler.host)
 813         } else {
 814             compiler
 815         };
 816
 817         if !builder.config.compiler_docs {
 818             builder.info("\tskipping - compiler/librustdoc docs disabled");
 819             return;
 820         }
 821
 822         // Build rustc docs so that we generate relative links.
 823         builder.ensure(Rustc { stage, target });
 824
 825         // Build rustdoc.
 826         builder.ensure(tool::Rustdoc { compiler: compiler });
 827
 828         // Symlink compiler docs to the output directory of rustdoc documentation.
 829         let out_dir = builder.stage_out(compiler, Mode::ToolRustc)
 830             .join(target)
 831             .join("doc");
 832         t!(fs::create_dir_all(&out_dir));
 833         t!(symlink_dir_force(&builder.config, &out, &out_dir));
 834
 835         // Build cargo command.
 836         let mut cargo = prepare_tool_cargo(
 837             builder,
 838             compiler,
 839             Mode::ToolRustc,
 840             target,
 841             "doc",
 842             "src/tools/rustdoc",
 843             SourceType::InTree,
 844             &[]
 845         );
 846
 847         // Only include compiler crates, no dependencies of those, such as `libc`.
 848         cargo.arg("--no-deps");
 849         cargo.arg("-p").arg("rustdoc");
 850
 851         cargo.env("RUSTDOCFLAGS", "--document-private-items");
 852         builder.run(&mut cargo);
 853     }
 854 }
 855
 856 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 857 pub struct ErrorIndex {
 858     target: Interned<String>,
 859 }
 860
 861 impl Step for ErrorIndex {
 862     type Output = ();
 863     const DEFAULT: bool = true;
 864     const ONLY_HOSTS: bool = true;
 865
 866     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 867         let builder = run.builder;
 868         run.path("src/tools/error_index_generator").default_condition(builder.config.docs)
 869     }
 870
 871     fn make_run(run: RunConfig<'_>) {
 872         run.builder.ensure(ErrorIndex {
 873             target: run.target,
 874         });
 875     }
 876
 877     /// Generates the HTML rendered error-index by running the
 878     /// `error_index_generator` tool.
 879     fn run(self, builder: &Builder<'_>) {
 880         let target = self.target;
 881
 882         builder.info(&format!("Documenting error index ({})", target));
 883         let out = builder.doc_out(target);
 884         t!(fs::create_dir_all(&out));
 885         let compiler = builder.compiler(2, builder.config.build);
 886         let mut index = tool::ErrorIndex::command(
 887             builder,
 888             compiler,
 889         );
 890         index.arg("html");
 891         index.arg(out.join("error-index.html"));
 892
 893         // FIXME: shouldn't have to pass this env var
 894         index.env("CFG_BUILD", &builder.config.build)
 895              .env("RUSTC_ERROR_METADATA_DST", builder.extended_error_dir());
 896
 897         builder.run(&mut index);
 898     }
 899 }
 900
 901 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 902 pub struct UnstableBookGen {
 903     target: Interned<String>,
 904 }
 905
 906 impl Step for UnstableBookGen {
 907     type Output = ();
 908     const DEFAULT: bool = true;
 909     const ONLY_HOSTS: bool = true;
 910
 911     fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
 912         let builder = run.builder;
 913         run.path("src/tools/unstable-book-gen").default_condition(builder.config.docs)
 914     }
 915
 916     fn make_run(run: RunConfig<'_>) {
 917         run.builder.ensure(UnstableBookGen {
 918             target: run.target,
 919         });
 920     }
 921
 922     fn run(self, builder: &Builder<'_>) {
 923         let target = self.target;
 924
 925         builder.ensure(compile::Std {
 926             compiler: builder.compiler(builder.top_stage, builder.config.build),
 927             target,
 928         });
 929
 930         builder.info(&format!("Generating unstable book md files ({})", target));
 931         let out = builder.md_doc_out(target).join("unstable-book");
 932         builder.create_dir(&out);
 933         builder.remove_dir(&out);
 934         let mut cmd = builder.tool_cmd(Tool::UnstableBookGen);
 935         cmd.arg(builder.src.join("src"));
 936         cmd.arg(out);
 937
 938         builder.run(&mut cmd);
 939     }
 940 }
 941
 942 fn symlink_dir_force(config: &Config, src: &Path, dst: &Path) -> io::Result<()> {
 943     if config.dry_run {
 944         return Ok(());
 945     }
 946     if let Ok(m) = fs::symlink_metadata(dst) {
 947         if m.file_type().is_dir() {
 948             fs::remove_dir_all(dst)?;
 949         } else {
 950             // handle directory junctions on windows by falling back to
 951             // `remove_dir`.
 952             fs::remove_file(dst).or_else(|_| {
 953                 fs::remove_dir(dst)
 954             })?;
 955         }
 956     }
 957
 958     symlink_dir(config, src, dst)
 959 }