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