src/bootstrap/doc.rs

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