1 //! Documentation generation for rustbuilder.
3 //! This module implements generation for all bits and pieces of documentation
4 //! for the Rust project. This notably includes suites like the rust book, the
5 //! nomicon, rust by example, standalone documentation, etc.
7 //! Everything here is basically just a shim around calling either `rustbook` or
10 use std::collections::HashSet;
13 use std::path::{PathBuf, Path};
16 use build_helper::{t, up_to_date};
18 use crate::util::symlink_dir;
19 use crate::builder::{Builder, Compiler, RunConfig, ShouldRun, Step};
20 use crate::tool::{self, prepare_tool_cargo, Tool, SourceType};
22 use crate::cache::{INTERNER, Interned};
23 use crate::config::Config;
26 ($($name:ident, $path:expr, $book_name:expr, $book_ver:expr;)+) => {
28 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
30 target: Interned<String>,
35 const DEFAULT: bool = true;
37 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
38 let builder = run.builder;
39 run.path($path).default_condition(builder.config.docs)
42 fn make_run(run: RunConfig<'_>) {
43 run.builder.ensure($name {
48 fn run(self, builder: &Builder<'_>) {
49 builder.ensure(Rustbook {
51 name: INTERNER.intern_str($book_name),
60 // NOTE: When adding a book here, make sure to ALSO build the book by
61 // adding a build step in `src/bootstrap/builder.rs`!
63 EditionGuide, "src/doc/edition-guide", "edition-guide", RustbookVersion::MdBook2;
64 EmbeddedBook, "src/doc/embedded-book", "embedded-book", RustbookVersion::MdBook2;
65 Nomicon, "src/doc/nomicon", "nomicon", RustbookVersion::MdBook1;
66 Reference, "src/doc/reference", "reference", RustbookVersion::MdBook1;
67 RustByExample, "src/doc/rust-by-example", "rust-by-example", RustbookVersion::MdBook1;
68 RustcBook, "src/doc/rustc", "rustc", RustbookVersion::MdBook1;
69 RustdocBook, "src/doc/rustdoc", "rustdoc", RustbookVersion::MdBook1;
72 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
73 enum RustbookVersion {
78 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
80 target: Interned<String>,
81 name: Interned<String>,
82 version: RustbookVersion,
85 impl Step for Rustbook {
88 // rustbook is never directly called, and only serves as a shim for the nomicon and the
90 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
94 /// Invoke `rustbook` for `target` for the doc book `name`.
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 {
103 src: INTERNER.intern_path(src),
104 version: self.version,
109 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
110 pub struct UnstableBook {
111 target: Interned<String>,
114 impl Step for UnstableBook {
116 const DEFAULT: bool = true;
118 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
119 let builder = run.builder;
120 run.path("src/doc/unstable-book").default_condition(builder.config.docs)
123 fn make_run(run: RunConfig<'_>) {
124 run.builder.ensure(UnstableBook {
129 fn run(self, builder: &Builder<'_>) {
130 builder.ensure(UnstableBookGen {
133 builder.ensure(RustbookSrc {
135 name: INTERNER.intern_str("unstable-book"),
136 src: builder.md_doc_out(self.target),
137 version: RustbookVersion::MdBook1,
142 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
143 pub struct CargoBook {
144 target: Interned<String>,
145 name: Interned<String>,
148 impl Step for CargoBook {
150 const DEFAULT: bool = true;
152 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
153 let builder = run.builder;
154 run.path("src/tools/cargo/src/doc/book").default_condition(builder.config.docs)
157 fn make_run(run: RunConfig<'_>) {
158 run.builder.ensure(CargoBook {
160 name: INTERNER.intern_str("cargo"),
164 fn run(self, builder: &Builder<'_>) {
165 let target = self.target;
166 let name = self.name;
167 let src = builder.src.join("src/tools/cargo/src/doc");
169 let out = builder.doc_out(target);
170 t!(fs::create_dir_all(&out));
172 let out = out.join(name);
174 builder.info(&format!("Cargo Book ({}) - {}", target, name));
176 let _ = fs::remove_dir_all(&out);
178 builder.run(builder.tool_cmd(Tool::Rustbook)
186 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
188 target: Interned<String>,
189 name: Interned<String>,
190 src: Interned<PathBuf>,
191 version: RustbookVersion,
194 impl Step for RustbookSrc {
197 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
201 /// Invoke `rustbook` for `target` for the doc book `name` from the `src` path.
203 /// This will not actually generate any documentation if the documentation has
204 /// already been generated.
205 fn run(self, builder: &Builder<'_>) {
206 let target = self.target;
207 let name = self.name;
209 let out = builder.doc_out(target);
210 t!(fs::create_dir_all(&out));
212 let out = out.join(name);
213 let src = src.join(name);
214 let index = out.join("index.html");
215 let rustbook = builder.tool_exe(Tool::Rustbook);
216 let mut rustbook_cmd = builder.tool_cmd(Tool::Rustbook);
217 if up_to_date(&src, &index) && up_to_date(&rustbook, &index) {
220 builder.info(&format!("Rustbook ({}) - {}", target, name));
221 let _ = fs::remove_dir_all(&out);
223 let vers = match self.version {
224 RustbookVersion::MdBook1 => "1",
225 RustbookVersion::MdBook2 => "2",
228 builder.run(rustbook_cmd
238 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
241 target: Interned<String>,
245 impl Step for TheBook {
247 const DEFAULT: bool = true;
249 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
250 let builder = run.builder;
251 run.path("src/doc/book").default_condition(builder.config.docs)
254 fn make_run(run: RunConfig<'_>) {
255 run.builder.ensure(TheBook {
256 compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
262 /// Builds the book and associated stuff.
264 /// We need to build:
266 /// * Book (first edition)
267 /// * Book (second edition)
268 /// * Version info and CSS
271 fn run(self, builder: &Builder<'_>) {
272 let compiler = self.compiler;
273 let target = self.target;
274 let name = self.name;
277 builder.ensure(Rustbook {
279 name: INTERNER.intern_string(name.to_string()),
280 version: RustbookVersion::MdBook2,
283 // building older edition redirects
285 let source_name = format!("{}/first-edition", name);
286 builder.ensure(Rustbook {
288 name: INTERNER.intern_string(source_name),
289 version: RustbookVersion::MdBook2,
292 let source_name = format!("{}/second-edition", name);
293 builder.ensure(Rustbook {
295 name: INTERNER.intern_string(source_name),
296 version: RustbookVersion::MdBook2,
299 let source_name = format!("{}/2018-edition", name);
300 builder.ensure(Rustbook {
302 name: INTERNER.intern_string(source_name),
303 version: RustbookVersion::MdBook2,
306 // build the version info page and CSS
307 builder.ensure(Standalone {
312 // build the redirect pages
313 builder.info(&format!("Documenting book redirect pages ({})", target));
314 for file in t!(fs::read_dir(builder.src.join("src/doc/book/redirects"))) {
316 let path = file.path();
317 let path = path.to_str().unwrap();
319 invoke_rustdoc(builder, compiler, target, path);
325 builder: &Builder<'_>,
327 target: Interned<String>,
330 let out = builder.doc_out(target);
332 let path = builder.src.join("src/doc").join(markdown);
334 let header = builder.src.join("src/doc/redirect.inc");
335 let footer = builder.src.join("src/doc/footer.inc");
336 let version_info = out.join("version_info.html");
338 let mut cmd = builder.rustdoc_cmd(compiler);
340 let out = out.join("book");
342 cmd.arg("--html-after-content").arg(&footer)
343 .arg("--html-before-content").arg(&version_info)
344 .arg("--html-in-header").arg(&header)
345 .arg("--markdown-no-toc")
346 .arg("--markdown-playground-url").arg("https://play.rust-lang.org/")
347 .arg("-o").arg(&out).arg(&path)
348 .arg("--markdown-css").arg("../rust.css");
350 builder.run(&mut cmd);
353 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
354 pub struct Standalone {
356 target: Interned<String>,
359 impl Step for Standalone {
361 const DEFAULT: bool = true;
363 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
364 let builder = run.builder;
365 run.path("src/doc").default_condition(builder.config.docs)
368 fn make_run(run: RunConfig<'_>) {
369 run.builder.ensure(Standalone {
370 compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
375 /// Generates all standalone documentation as compiled by the rustdoc in `stage`
376 /// for the `target` into `out`.
378 /// This will list all of `src/doc` looking for markdown files and appropriately
379 /// perform transformations like substituting `VERSION`, `SHORT_HASH`, and
380 /// `STAMP` along with providing the various header/footer HTML we've customized.
382 /// In the end, this is just a glorified wrapper around rustdoc!
383 fn run(self, builder: &Builder<'_>) {
384 let target = self.target;
385 let compiler = self.compiler;
386 builder.info(&format!("Documenting standalone ({})", target));
387 let out = builder.doc_out(target);
388 t!(fs::create_dir_all(&out));
390 let favicon = builder.src.join("src/doc/favicon.inc");
391 let footer = builder.src.join("src/doc/footer.inc");
392 let full_toc = builder.src.join("src/doc/full-toc.inc");
393 t!(fs::copy(builder.src.join("src/doc/rust.css"), out.join("rust.css")));
395 let version_input = builder.src.join("src/doc/version_info.html.template");
396 let version_info = out.join("version_info.html");
398 if !builder.config.dry_run && !up_to_date(&version_input, &version_info) {
399 let info = t!(fs::read_to_string(&version_input))
400 .replace("VERSION", &builder.rust_release())
401 .replace("SHORT_HASH", builder.rust_info.sha_short().unwrap_or(""))
402 .replace("STAMP", builder.rust_info.sha().unwrap_or(""));
403 t!(fs::write(&version_info, &info));
406 for file in t!(fs::read_dir(builder.src.join("src/doc"))) {
408 let path = file.path();
409 let filename = path.file_name().unwrap().to_str().unwrap();
410 if !filename.ends_with(".md") || filename == "README.md" {
414 let html = out.join(filename).with_extension("html");
415 let rustdoc = builder.rustdoc(compiler);
416 if up_to_date(&path, &html) &&
417 up_to_date(&footer, &html) &&
418 up_to_date(&favicon, &html) &&
419 up_to_date(&full_toc, &html) &&
420 up_to_date(&version_info, &html) &&
421 (builder.config.dry_run || up_to_date(&rustdoc, &html)) {
425 let mut cmd = builder.rustdoc_cmd(compiler);
426 cmd.arg("--html-after-content").arg(&footer)
427 .arg("--html-before-content").arg(&version_info)
428 .arg("--html-in-header").arg(&favicon)
429 .arg("--markdown-no-toc")
430 .arg("--index-page").arg(&builder.src.join("src/doc/index.md"))
431 .arg("--markdown-playground-url").arg("https://play.rust-lang.org/")
435 if filename == "not_found.md" {
436 cmd.arg("--markdown-css")
437 .arg("https://doc.rust-lang.org/rust.css");
439 cmd.arg("--markdown-css").arg("rust.css");
441 builder.run(&mut cmd);
446 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
449 pub target: Interned<String>,
454 const DEFAULT: bool = true;
456 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
457 let builder = run.builder;
458 run.all_krates("std").default_condition(builder.config.docs)
461 fn make_run(run: RunConfig<'_>) {
462 run.builder.ensure(Std {
463 stage: run.builder.top_stage,
468 /// Compile all standard library documentation.
470 /// This will generate all documentation for the standard library and its
471 /// dependencies. This is largely just a wrapper around `cargo doc`.
472 fn run(self, builder: &Builder<'_>) {
473 let stage = self.stage;
474 let target = self.target;
475 builder.info(&format!("Documenting stage{} std ({})", stage, target));
476 let out = builder.doc_out(target);
477 t!(fs::create_dir_all(&out));
478 let compiler = builder.compiler(stage, builder.config.build);
479 let compiler = if builder.force_use_stage1(compiler, target) {
480 builder.compiler(1, compiler.host)
485 builder.ensure(compile::Std { compiler, target });
486 let out_dir = builder.stage_out(compiler, Mode::Std)
487 .join(target).join("doc");
489 // Here what we're doing is creating a *symlink* (directory junction on
490 // Windows) to the final output location. This is not done as an
491 // optimization but rather for correctness. We've got three trees of
492 // documentation, one for std, one for test, and one for rustc. It's then
493 // our job to merge them all together.
495 // Unfortunately rustbuild doesn't know nearly as well how to merge doc
496 // trees as rustdoc does itself, so instead of actually having three
497 // separate trees we just have rustdoc output to the same location across
500 // This way rustdoc generates output directly into the output, and rustdoc
501 // will also directly handle merging.
502 let my_out = builder.crate_doc_out(target);
503 t!(symlink_dir_force(&builder.config, &my_out, &out_dir));
504 t!(fs::copy(builder.src.join("src/doc/rust.css"), out.join("rust.css")));
506 let run_cargo_rustdoc_for = |package: &str| {
507 let mut cargo = builder.cargo(compiler, Mode::Std, target, "rustdoc");
508 compile::std_cargo(builder, &compiler, target, &mut cargo);
510 // Keep a whitelist so we do not build internal stdlib crates, these will be
511 // build by the rustc step later if enabled.
512 cargo.arg("-Z").arg("unstable-options")
513 .arg("-p").arg(package);
514 // Create all crate output directories first to make sure rustdoc uses
516 // FIXME: Cargo should probably do this itself.
517 t!(fs::create_dir_all(out_dir.join(package)));
519 .arg("--markdown-css").arg("rust.css")
520 .arg("--markdown-no-toc")
521 .arg("--generate-redirect-pages")
522 .arg("--resource-suffix").arg(crate::channel::CFG_RELEASE_NUM)
523 .arg("--index-page").arg(&builder.src.join("src/doc/index.md"));
525 builder.run(&mut cargo);
526 builder.cp_r(&my_out, &out);
528 for krate in &["alloc", "core", "std"] {
529 run_cargo_rustdoc_for(krate);
534 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
537 target: Interned<String>,
542 const DEFAULT: bool = true;
544 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
545 let builder = run.builder;
546 run.krate("test").default_condition(builder.config.docs)
549 fn make_run(run: RunConfig<'_>) {
550 run.builder.ensure(Test {
551 stage: run.builder.top_stage,
556 /// Compile all libtest documentation.
558 /// This will generate all documentation for libtest and its dependencies. This
559 /// is largely just a wrapper around `cargo doc`.
560 fn run(self, builder: &Builder<'_>) {
561 let stage = self.stage;
562 let target = self.target;
563 builder.info(&format!("Documenting stage{} test ({})", stage, target));
564 let out = builder.doc_out(target);
565 t!(fs::create_dir_all(&out));
566 let compiler = builder.compiler(stage, builder.config.build);
567 let compiler = if builder.force_use_stage1(compiler, target) {
568 builder.compiler(1, compiler.host)
573 // Build libstd docs so that we generate relative links
574 builder.ensure(Std { stage, target });
576 builder.ensure(compile::Test { compiler, target });
577 let out_dir = builder.stage_out(compiler, Mode::Test)
578 .join(target).join("doc");
580 // See docs in std above for why we symlink
581 let my_out = builder.crate_doc_out(target);
582 t!(symlink_dir_force(&builder.config, &my_out, &out_dir));
584 let mut cargo = builder.cargo(compiler, Mode::Test, target, "doc");
585 compile::test_cargo(builder, &compiler, target, &mut cargo);
587 cargo.arg("--no-deps")
588 .arg("-p").arg("test")
589 .env("RUSTDOC_RESOURCE_SUFFIX", crate::channel::CFG_RELEASE_NUM)
590 .env("RUSTDOC_GENERATE_REDIRECT_PAGES", "1");
592 builder.run(&mut cargo);
593 builder.cp_r(&my_out, &out);
597 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
598 pub struct WhitelistedRustc {
600 target: Interned<String>,
603 impl Step for WhitelistedRustc {
605 const DEFAULT: bool = true;
606 const ONLY_HOSTS: bool = true;
608 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
609 let builder = run.builder;
610 run.krate("rustc-main").default_condition(builder.config.docs)
613 fn make_run(run: RunConfig<'_>) {
614 run.builder.ensure(WhitelistedRustc {
615 stage: run.builder.top_stage,
620 /// Generates whitelisted compiler crate documentation.
622 /// This will generate all documentation for crates that are whitelisted
623 /// to be included in the standard documentation. This documentation is
624 /// included in the standard Rust documentation, so we should always
625 /// document it and symlink to merge with the rest of the std and test
626 /// documentation. We don't build other compiler documentation
627 /// here as we want to be able to keep it separate from the standard
628 /// documentation. This is largely just a wrapper around `cargo doc`.
629 fn run(self, builder: &Builder<'_>) {
630 let stage = self.stage;
631 let target = self.target;
632 builder.info(&format!("Documenting stage{} whitelisted compiler ({})", stage, target));
633 let out = builder.doc_out(target);
634 t!(fs::create_dir_all(&out));
635 let compiler = builder.compiler(stage, builder.config.build);
636 let compiler = if builder.force_use_stage1(compiler, target) {
637 builder.compiler(1, compiler.host)
642 // Build libstd docs so that we generate relative links
643 builder.ensure(Std { stage, target });
645 builder.ensure(compile::Rustc { compiler, target });
646 let out_dir = builder.stage_out(compiler, Mode::Rustc)
647 .join(target).join("doc");
649 // See docs in std above for why we symlink
650 let my_out = builder.crate_doc_out(target);
651 t!(symlink_dir_force(&builder.config, &my_out, &out_dir));
653 let mut cargo = builder.cargo(compiler, Mode::Rustc, target, "doc");
654 compile::rustc_cargo(builder, &mut cargo);
656 // We don't want to build docs for internal compiler dependencies in this
657 // step (there is another step for that). Therefore, we whitelist the crates
658 // for which docs must be built.
659 for krate in &["proc_macro"] {
660 cargo.arg("-p").arg(krate)
661 .env("RUSTDOC_RESOURCE_SUFFIX", crate::channel::CFG_RELEASE_NUM)
662 .env("RUSTDOC_GENERATE_REDIRECT_PAGES", "1");
665 builder.run(&mut cargo);
666 builder.cp_r(&my_out, &out);
670 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
673 target: Interned<String>,
676 impl Step for Rustc {
678 const DEFAULT: bool = true;
679 const ONLY_HOSTS: bool = true;
681 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
682 let builder = run.builder;
683 run.krate("rustc-main").default_condition(builder.config.docs)
686 fn make_run(run: RunConfig<'_>) {
687 run.builder.ensure(Rustc {
688 stage: run.builder.top_stage,
693 /// Generates compiler documentation.
695 /// This will generate all documentation for compiler and dependencies.
696 /// Compiler documentation is distributed separately, so we make sure
697 /// we do not merge it with the other documentation from std, test and
698 /// proc_macros. This is largely just a wrapper around `cargo doc`.
699 fn run(self, builder: &Builder<'_>) {
700 let stage = self.stage;
701 let target = self.target;
702 builder.info(&format!("Documenting stage{} compiler ({})", stage, target));
704 // This is the intended out directory for compiler documentation.
705 let out = builder.compiler_doc_out(target);
706 t!(fs::create_dir_all(&out));
708 // Get the correct compiler for this stage.
709 let compiler = builder.compiler(stage, builder.config.build);
710 let compiler = if builder.force_use_stage1(compiler, target) {
711 builder.compiler(1, compiler.host)
716 if !builder.config.compiler_docs {
717 builder.info("\tskipping - compiler/librustdoc docs disabled");
722 builder.ensure(compile::Rustc { compiler, target });
724 // We do not symlink to the same shared folder that already contains std library
725 // documentation from previous steps as we do not want to include that.
726 let out_dir = builder.stage_out(compiler, Mode::Rustc).join(target).join("doc");
727 t!(symlink_dir_force(&builder.config, &out, &out_dir));
729 // Build cargo command.
730 let mut cargo = builder.cargo(compiler, Mode::Rustc, target, "doc");
731 cargo.env("RUSTDOCFLAGS", "--document-private-items");
732 compile::rustc_cargo(builder, &mut cargo);
734 // Only include compiler crates, no dependencies of those, such as `libc`.
735 cargo.arg("--no-deps");
737 // Find dependencies for top level crates.
738 let mut compiler_crates = HashSet::new();
739 for root_crate in &["rustc_driver", "rustc_codegen_llvm", "rustc_codegen_ssa"] {
740 let interned_root_crate = INTERNER.intern_str(root_crate);
741 find_compiler_crates(builder, &interned_root_crate, &mut compiler_crates);
744 for krate in &compiler_crates {
745 // Create all crate output directories first to make sure rustdoc uses
747 // FIXME: Cargo should probably do this itself.
748 t!(fs::create_dir_all(out_dir.join(krate)));
749 cargo.arg("-p").arg(krate);
752 builder.run(&mut cargo);
756 fn find_compiler_crates(
757 builder: &Builder<'_>,
758 name: &Interned<String>,
759 crates: &mut HashSet<Interned<String>>
761 // Add current crate.
762 crates.insert(*name);
764 // Look for dependencies.
765 for dep in builder.crates.get(name).unwrap().deps.iter() {
766 if builder.crates.get(dep).unwrap().is_local(builder) {
767 find_compiler_crates(builder, dep, crates);
772 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
775 target: Interned<String>,
778 impl Step for Rustdoc {
780 const DEFAULT: bool = true;
781 const ONLY_HOSTS: bool = true;
783 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
784 run.krate("rustdoc-tool")
787 fn make_run(run: RunConfig<'_>) {
788 run.builder.ensure(Rustdoc {
789 stage: run.builder.top_stage,
794 /// Generates compiler documentation.
796 /// This will generate all documentation for compiler and dependencies.
797 /// Compiler documentation is distributed separately, so we make sure
798 /// we do not merge it with the other documentation from std, test and
799 /// proc_macros. This is largely just a wrapper around `cargo doc`.
800 fn run(self, builder: &Builder<'_>) {
801 let stage = self.stage;
802 let target = self.target;
803 builder.info(&format!("Documenting stage{} rustdoc ({})", stage, target));
805 // This is the intended out directory for compiler documentation.
806 let out = builder.compiler_doc_out(target);
807 t!(fs::create_dir_all(&out));
809 // Get the correct compiler for this stage.
810 let compiler = builder.compiler(stage, builder.config.build);
811 let compiler = if builder.force_use_stage1(compiler, target) {
812 builder.compiler(1, compiler.host)
817 if !builder.config.compiler_docs {
818 builder.info("\tskipping - compiler/librustdoc docs disabled");
822 // Build rustc docs so that we generate relative links.
823 builder.ensure(Rustc { stage, target });
826 builder.ensure(tool::Rustdoc { compiler: compiler });
828 // Symlink compiler docs to the output directory of rustdoc documentation.
829 let out_dir = builder.stage_out(compiler, Mode::ToolRustc)
832 t!(fs::create_dir_all(&out_dir));
833 t!(symlink_dir_force(&builder.config, &out, &out_dir));
835 // Build cargo command.
836 let mut cargo = prepare_tool_cargo(
847 // Only include compiler crates, no dependencies of those, such as `libc`.
848 cargo.arg("--no-deps");
849 cargo.arg("-p").arg("rustdoc");
851 cargo.env("RUSTDOCFLAGS", "--document-private-items");
852 builder.run(&mut cargo);
856 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
857 pub struct ErrorIndex {
858 target: Interned<String>,
861 impl Step for ErrorIndex {
863 const DEFAULT: bool = true;
864 const ONLY_HOSTS: bool = true;
866 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
867 let builder = run.builder;
868 run.path("src/tools/error_index_generator").default_condition(builder.config.docs)
871 fn make_run(run: RunConfig<'_>) {
872 run.builder.ensure(ErrorIndex {
877 /// Generates the HTML rendered error-index by running the
878 /// `error_index_generator` tool.
879 fn run(self, builder: &Builder<'_>) {
880 let target = self.target;
882 builder.info(&format!("Documenting error index ({})", target));
883 let out = builder.doc_out(target);
884 t!(fs::create_dir_all(&out));
885 let compiler = builder.compiler(2, builder.config.build);
886 let mut index = tool::ErrorIndex::command(
891 index.arg(out.join("error-index.html"));
892 index.arg(crate::channel::CFG_RELEASE_NUM);
894 // FIXME: shouldn't have to pass this env var
895 index.env("CFG_BUILD", &builder.config.build)
896 .env("RUSTC_ERROR_METADATA_DST", builder.extended_error_dir());
898 builder.run(&mut index);
902 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
903 pub struct UnstableBookGen {
904 target: Interned<String>,
907 impl Step for UnstableBookGen {
909 const DEFAULT: bool = true;
910 const ONLY_HOSTS: bool = true;
912 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
913 let builder = run.builder;
914 run.path("src/tools/unstable-book-gen").default_condition(builder.config.docs)
917 fn make_run(run: RunConfig<'_>) {
918 run.builder.ensure(UnstableBookGen {
923 fn run(self, builder: &Builder<'_>) {
924 let target = self.target;
926 builder.ensure(compile::Std {
927 compiler: builder.compiler(builder.top_stage, builder.config.build),
931 builder.info(&format!("Generating unstable book md files ({})", target));
932 let out = builder.md_doc_out(target).join("unstable-book");
933 builder.create_dir(&out);
934 builder.remove_dir(&out);
935 let mut cmd = builder.tool_cmd(Tool::UnstableBookGen);
936 cmd.arg(builder.src.join("src"));
939 builder.run(&mut cmd);
943 fn symlink_dir_force(config: &Config, src: &Path, dst: &Path) -> io::Result<()> {
947 if let Ok(m) = fs::symlink_metadata(dst) {
948 if m.file_type().is_dir() {
949 fs::remove_dir_all(dst)?;
951 // handle directory junctions on windows by falling back to
953 fs::remove_file(dst).or_else(|_| {
959 symlink_dir(config, src, dst)