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