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::{Path, PathBuf};
15 use crate::builder::{Builder, Compiler, Kind, RunConfig, ShouldRun, Step};
16 use crate::cache::{Interned, INTERNER};
18 use crate::config::{Config, TargetSelection};
19 use crate::tool::{self, prepare_tool_cargo, SourceType, Tool};
20 use crate::util::{symlink_dir, t, up_to_date};
23 macro_rules! submodule_helper {
24 ($path:expr, submodule) => {
27 ($path:expr, submodule = $submodule:literal) => {
33 ($($name:ident, $path:expr, $book_name:expr $(, submodule $(= $submodule:literal)? )? ;)+) => {
35 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
37 target: TargetSelection,
42 const DEFAULT: bool = true;
44 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
45 let builder = run.builder;
46 run.path($path).default_condition(builder.config.docs)
49 fn make_run(run: RunConfig<'_>) {
50 run.builder.ensure($name {
55 fn run(self, builder: &Builder<'_>) {
57 let path = Path::new(submodule_helper!( $path, submodule $( = $submodule )? ));
58 builder.update_submodule(&path);
60 builder.ensure(RustbookSrc {
62 name: INTERNER.intern_str($book_name),
63 src: INTERNER.intern_path(builder.src.join($path)),
71 // NOTE: When adding a book here, make sure to ALSO build the book by
72 // adding a build step in `src/bootstrap/builder.rs`!
73 // NOTE: Make sure to add the corresponding submodule when adding a new book.
74 // FIXME: Make checking for a submodule automatic somehow (maybe by having a list of all submodules
75 // and checking against it?).
77 CargoBook, "src/tools/cargo/src/doc", "cargo", submodule = "src/tools/cargo";
78 EditionGuide, "src/doc/edition-guide", "edition-guide", submodule;
79 EmbeddedBook, "src/doc/embedded-book", "embedded-book", submodule;
80 Nomicon, "src/doc/nomicon", "nomicon", submodule;
81 Reference, "src/doc/reference", "reference", submodule;
82 RustByExample, "src/doc/rust-by-example", "rust-by-example", submodule;
83 RustdocBook, "src/doc/rustdoc", "rustdoc";
86 fn open(builder: &Builder<'_>, path: impl AsRef<Path>) {
87 if builder.config.dry_run || !builder.config.cmd.open() {
91 let path = path.as_ref();
92 builder.info(&format!("Opening doc {}", path.display()));
93 if let Err(err) = opener::open(path) {
94 builder.info(&format!("{}\n", err));
98 // "library/std" -> ["library", "std"]
100 // Used for deciding whether a particular step is one requested by the user on
101 // the `x.py doc` command line, which determines whether `--open` will open that
103 pub(crate) fn components_simplified(path: &PathBuf) -> Vec<&str> {
104 path.iter().map(|component| component.to_str().unwrap_or("???")).collect()
107 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
108 pub struct UnstableBook {
109 target: TargetSelection,
112 impl Step for UnstableBook {
114 const DEFAULT: bool = true;
116 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
117 let builder = run.builder;
118 run.path("src/doc/unstable-book").default_condition(builder.config.docs)
121 fn make_run(run: RunConfig<'_>) {
122 run.builder.ensure(UnstableBook { target: run.target });
125 fn run(self, builder: &Builder<'_>) {
126 builder.ensure(UnstableBookGen { target: self.target });
127 builder.ensure(RustbookSrc {
129 name: INTERNER.intern_str("unstable-book"),
130 src: INTERNER.intern_path(builder.md_doc_out(self.target).join("unstable-book")),
135 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
137 target: TargetSelection,
138 name: Interned<String>,
139 src: Interned<PathBuf>,
142 impl Step for RustbookSrc {
145 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
149 /// Invoke `rustbook` for `target` for the doc book `name` from the `src` path.
151 /// This will not actually generate any documentation if the documentation has
152 /// already been generated.
153 fn run(self, builder: &Builder<'_>) {
154 let target = self.target;
155 let name = self.name;
157 let out = builder.doc_out(target);
158 t!(fs::create_dir_all(&out));
160 let out = out.join(name);
161 let index = out.join("index.html");
162 let rustbook = builder.tool_exe(Tool::Rustbook);
163 let mut rustbook_cmd = builder.tool_cmd(Tool::Rustbook);
164 if builder.config.dry_run || up_to_date(&src, &index) && up_to_date(&rustbook, &index) {
167 builder.info(&format!("Rustbook ({}) - {}", target, name));
168 let _ = fs::remove_dir_all(&out);
170 builder.run(rustbook_cmd.arg("build").arg(&src).arg("-d").arg(out));
174 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
177 target: TargetSelection,
180 impl Step for TheBook {
182 const DEFAULT: bool = true;
184 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
185 let builder = run.builder;
186 run.path("src/doc/book").default_condition(builder.config.docs)
189 fn make_run(run: RunConfig<'_>) {
190 run.builder.ensure(TheBook {
191 compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
196 /// Builds the book and associated stuff.
198 /// We need to build:
201 /// * Older edition redirects
202 /// * Version info and CSS
205 fn run(self, builder: &Builder<'_>) {
206 let relative_path = Path::new("src").join("doc").join("book");
207 builder.update_submodule(&relative_path);
209 let compiler = self.compiler;
210 let target = self.target;
213 builder.ensure(RustbookSrc {
215 name: INTERNER.intern_str("book"),
216 src: INTERNER.intern_path(builder.src.join(&relative_path)),
219 // building older edition redirects
220 for edition in &["first-edition", "second-edition", "2018-edition"] {
221 builder.ensure(RustbookSrc {
223 name: INTERNER.intern_string(format!("book/{}", edition)),
224 src: INTERNER.intern_path(builder.src.join(&relative_path).join(edition)),
228 // build the version info page and CSS
229 builder.ensure(Standalone { compiler, target });
231 // build the redirect pages
232 builder.info(&format!("Documenting book redirect pages ({})", target));
233 for file in t!(fs::read_dir(builder.src.join(&relative_path).join("redirects"))) {
235 let path = file.path();
236 let path = path.to_str().unwrap();
238 invoke_rustdoc(builder, compiler, target, path);
241 if builder.was_invoked_explicitly::<Self>(Kind::Doc) {
242 let out = builder.doc_out(target);
243 let index = out.join("book").join("index.html");
244 open(builder, &index);
250 builder: &Builder<'_>,
252 target: TargetSelection,
255 let out = builder.doc_out(target);
257 let path = builder.src.join("src/doc").join(markdown);
259 let header = builder.src.join("src/doc/redirect.inc");
260 let footer = builder.src.join("src/doc/footer.inc");
261 let version_info = out.join("version_info.html");
263 let mut cmd = builder.rustdoc_cmd(compiler);
265 let out = out.join("book");
267 cmd.arg("--html-after-content")
269 .arg("--html-before-content")
271 .arg("--html-in-header")
273 .arg("--markdown-no-toc")
274 .arg("--markdown-playground-url")
275 .arg("https://play.rust-lang.org/")
279 .arg("--markdown-css")
282 if !builder.config.docs_minification {
283 cmd.arg("-Z").arg("unstable-options").arg("--disable-minification");
286 builder.run(&mut cmd);
289 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
290 pub struct Standalone {
292 target: TargetSelection,
295 impl Step for Standalone {
297 const DEFAULT: bool = true;
299 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
300 let builder = run.builder;
301 run.path("src/doc").default_condition(builder.config.docs)
304 fn make_run(run: RunConfig<'_>) {
305 run.builder.ensure(Standalone {
306 compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
311 /// Generates all standalone documentation as compiled by the rustdoc in `stage`
312 /// for the `target` into `out`.
314 /// This will list all of `src/doc` looking for markdown files and appropriately
315 /// perform transformations like substituting `VERSION`, `SHORT_HASH`, and
316 /// `STAMP` along with providing the various header/footer HTML we've customized.
318 /// In the end, this is just a glorified wrapper around rustdoc!
319 fn run(self, builder: &Builder<'_>) {
320 let target = self.target;
321 let compiler = self.compiler;
322 builder.info(&format!("Documenting standalone ({})", target));
323 let out = builder.doc_out(target);
324 t!(fs::create_dir_all(&out));
326 let favicon = builder.src.join("src/doc/favicon.inc");
327 let footer = builder.src.join("src/doc/footer.inc");
328 let full_toc = builder.src.join("src/doc/full-toc.inc");
329 t!(fs::copy(builder.src.join("src/doc/rust.css"), out.join("rust.css")));
331 let version_input = builder.src.join("src/doc/version_info.html.template");
332 let version_info = out.join("version_info.html");
334 if !builder.config.dry_run && !up_to_date(&version_input, &version_info) {
335 let info = t!(fs::read_to_string(&version_input))
336 .replace("VERSION", &builder.rust_release())
337 .replace("SHORT_HASH", builder.rust_info.sha_short().unwrap_or(""))
338 .replace("STAMP", builder.rust_info.sha().unwrap_or(""));
339 t!(fs::write(&version_info, &info));
342 for file in t!(fs::read_dir(builder.src.join("src/doc"))) {
344 let path = file.path();
345 let filename = path.file_name().unwrap().to_str().unwrap();
346 if !filename.ends_with(".md") || filename == "README.md" {
350 let html = out.join(filename).with_extension("html");
351 let rustdoc = builder.rustdoc(compiler);
352 if up_to_date(&path, &html)
353 && up_to_date(&footer, &html)
354 && up_to_date(&favicon, &html)
355 && up_to_date(&full_toc, &html)
356 && (builder.config.dry_run || up_to_date(&version_info, &html))
357 && (builder.config.dry_run || up_to_date(&rustdoc, &html))
362 let mut cmd = builder.rustdoc_cmd(compiler);
363 // Needed for --index-page flag
364 cmd.arg("-Z").arg("unstable-options");
366 cmd.arg("--html-after-content")
368 .arg("--html-before-content")
370 .arg("--html-in-header")
372 .arg("--markdown-no-toc")
374 .arg(&builder.src.join("src/doc/index.md"))
375 .arg("--markdown-playground-url")
376 .arg("https://play.rust-lang.org/")
381 if !builder.config.docs_minification {
382 cmd.arg("--disable-minification");
385 if filename == "not_found.md" {
386 cmd.arg("--markdown-css")
387 .arg(format!("https://doc.rust-lang.org/rustdoc{}.css", &builder.version))
388 .arg("--markdown-css")
389 .arg("https://doc.rust-lang.org/rust.css");
391 cmd.arg("--markdown-css")
392 .arg(format!("rustdoc{}.css", &builder.version))
393 .arg("--markdown-css")
396 builder.run(&mut cmd);
399 // We open doc/index.html as the default if invoked as `x.py doc --open`
400 // with no particular explicit doc requested (e.g. library/core).
401 if builder.paths.is_empty() || builder.was_invoked_explicitly::<Self>(Kind::Doc) {
402 let index = out.join("index.html");
403 open(builder, &index);
408 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
411 pub target: TargetSelection,
416 const DEFAULT: bool = true;
418 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
419 let builder = run.builder;
420 run.all_krates("test").default_condition(builder.config.docs)
423 fn make_run(run: RunConfig<'_>) {
424 run.builder.ensure(Std { stage: run.builder.top_stage, target: run.target });
427 /// Compile all standard library documentation.
429 /// This will generate all documentation for the standard library and its
430 /// dependencies. This is largely just a wrapper around `cargo doc`.
431 fn run(self, builder: &Builder<'_>) {
432 let stage = self.stage;
433 let target = self.target;
434 builder.info(&format!("Documenting stage{} std ({})", stage, target));
435 let out = builder.doc_out(target);
436 t!(fs::create_dir_all(&out));
437 let compiler = builder.compiler(stage, builder.config.build);
439 builder.ensure(compile::Std { compiler, target });
440 let out_dir = builder.stage_out(compiler, Mode::Std).join(target.triple).join("doc");
442 t!(fs::copy(builder.src.join("src/doc/rust.css"), out.join("rust.css")));
444 let run_cargo_rustdoc_for = |package: &str| {
446 builder.cargo(compiler, Mode::Std, SourceType::InTree, target, "rustdoc");
447 compile::std_cargo(builder, target, compiler.stage, &mut cargo);
452 .arg("-Zskip-rustdoc-fingerprint")
454 .arg("--markdown-css")
456 .arg("--markdown-no-toc")
458 .arg("unstable-options")
459 .arg("--resource-suffix")
460 .arg(&builder.version)
462 .arg(&builder.src.join("src/doc/index.md"));
464 if !builder.config.docs_minification {
465 cargo.arg("--disable-minification");
468 builder.run(&mut cargo.into());
474 .map(components_simplified)
476 if path.get(0) == Some(&"library") {
477 Some(path[1].to_owned())
478 } else if !path.is_empty() {
479 Some(path[0].to_owned())
484 .collect::<Vec<_>>();
486 // Only build the following crates. While we could just iterate over the
487 // folder structure, that would also build internal crates that we do
488 // not want to show in documentation. These crates will later be visited
489 // by the rustc step, so internal documentation will show them.
491 // Note that the order here is important! The crates need to be
492 // processed starting from the leaves, otherwise rustdoc will not
493 // create correct links between crates because rustdoc depends on the
494 // existence of the output directories to know if it should be a local
496 let krates = ["core", "alloc", "std", "proc_macro", "test"];
497 for krate in &krates {
498 run_cargo_rustdoc_for(krate);
499 if paths.iter().any(|p| p == krate) {
500 // No need to document more of the libraries if we have the one we want.
504 builder.cp_r(&out_dir, &out);
506 // Look for library/std, library/core etc in the `x.py doc` arguments and
507 // open the corresponding rendered docs.
508 for requested_crate in paths {
509 if krates.iter().any(|k| *k == requested_crate.as_str()) {
510 let index = out.join(requested_crate).join("index.html");
511 open(builder, &index);
517 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
520 pub target: TargetSelection,
523 impl Step for Rustc {
525 const DEFAULT: bool = true;
526 const ONLY_HOSTS: bool = true;
528 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
529 let builder = run.builder;
530 run.krate("rustc-main").path("compiler").default_condition(builder.config.compiler_docs)
533 fn make_run(run: RunConfig<'_>) {
534 run.builder.ensure(Rustc { stage: run.builder.top_stage, target: run.target });
537 /// Generates compiler documentation.
539 /// This will generate all documentation for compiler and dependencies.
540 /// Compiler documentation is distributed separately, so we make sure
541 /// we do not merge it with the other documentation from std, test and
542 /// proc_macros. This 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{} compiler ({})", stage, target));
551 .map(components_simplified)
553 if path.get(0) == Some(&"compiler") {
554 path.get(1).map(|p| p.to_owned())
559 .collect::<Vec<_>>();
561 // This is the intended out directory for compiler documentation.
562 let out = builder.compiler_doc_out(target);
563 t!(fs::create_dir_all(&out));
566 let compiler = builder.compiler(stage, builder.config.build);
567 builder.ensure(compile::Rustc { compiler, target });
569 // This uses a shared directory so that librustdoc documentation gets
570 // correctly built and merged with the rustc documentation. This is
571 // needed because rustdoc is built in a different directory from
572 // rustc. rustdoc needs to be able to see everything, for example when
573 // merging the search index, or generating local (relative) links.
574 let out_dir = builder.stage_out(compiler, Mode::Rustc).join(target.triple).join("doc");
575 t!(symlink_dir_force(&builder.config, &out, &out_dir));
576 // Cargo puts proc macros in `target/doc` even if you pass `--target`
577 // explicitly (https://github.com/rust-lang/cargo/issues/7677).
578 let proc_macro_out_dir = builder.stage_out(compiler, Mode::Rustc).join("doc");
579 t!(symlink_dir_force(&builder.config, &out, &proc_macro_out_dir));
581 // Build cargo command.
582 let mut cargo = builder.cargo(compiler, Mode::Rustc, SourceType::InTree, target, "doc");
583 cargo.rustdocflag("--document-private-items");
584 // Since we always pass --document-private-items, there's no need to warn about linking to private items.
585 cargo.rustdocflag("-Arustdoc::private-intra-doc-links");
586 cargo.rustdocflag("--enable-index-page");
587 cargo.rustdocflag("-Zunstable-options");
588 cargo.rustdocflag("-Znormalize-docs");
589 cargo.rustdocflag("--show-type-layout");
590 cargo.rustdocflag("--generate-link-to-definition");
591 compile::rustc_cargo(builder, &mut cargo, target);
592 cargo.arg("-Zunstable-options");
593 cargo.arg("-Zskip-rustdoc-fingerprint");
595 // Only include compiler crates, no dependencies of those, such as `libc`.
596 // Do link to dependencies on `docs.rs` however using `rustdoc-map`.
597 cargo.arg("--no-deps");
598 cargo.arg("-Zrustdoc-map");
600 // FIXME: `-Zrustdoc-map` does not yet correctly work for transitive dependencies,
601 // once this is no longer an issue the special case for `ena` can be removed.
602 cargo.rustdocflag("--extern-html-root-url");
603 cargo.rustdocflag("ena=https://docs.rs/ena/latest/");
605 let mut compiler_crates = HashSet::new();
607 if paths.is_empty() {
608 // Find dependencies for top level crates.
609 for root_crate in &["rustc_driver", "rustc_codegen_llvm", "rustc_codegen_ssa"] {
610 compiler_crates.extend(
612 .in_tree_crates(root_crate, Some(target))
614 .map(|krate| krate.name),
618 for root_crate in paths {
619 if !builder.src.join("compiler").join(&root_crate).exists() {
620 builder.info(&format!(
621 "\tskipping - compiler/{} (unknown compiler crate)",
625 compiler_crates.extend(
627 .in_tree_crates(root_crate, Some(target))
629 .map(|krate| krate.name),
635 let mut to_open = None;
636 for krate in &compiler_crates {
637 // Create all crate output directories first to make sure rustdoc uses
639 // FIXME: Cargo should probably do this itself.
640 t!(fs::create_dir_all(out_dir.join(krate)));
641 cargo.arg("-p").arg(krate);
642 if to_open.is_none() {
643 to_open = Some(krate);
647 builder.run(&mut cargo.into());
648 // Let's open the first crate documentation page:
649 if let Some(krate) = to_open {
650 let index = out.join(krate).join("index.html");
651 open(builder, &index);
656 macro_rules! tool_doc {
657 ($tool: ident, $should_run: literal, $path: literal, [$($krate: literal),+ $(,)?] $(,)?) => {
658 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
661 target: TargetSelection,
664 impl Step for $tool {
666 const DEFAULT: bool = true;
667 const ONLY_HOSTS: bool = true;
669 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
670 let builder = run.builder;
671 run.krate($should_run).default_condition(builder.config.compiler_docs)
674 fn make_run(run: RunConfig<'_>) {
675 run.builder.ensure($tool { stage: run.builder.top_stage, target: run.target });
678 /// Generates compiler documentation.
680 /// This will generate all documentation for compiler and dependencies.
681 /// Compiler documentation is distributed separately, so we make sure
682 /// we do not merge it with the other documentation from std, test and
683 /// proc_macros. This is largely just a wrapper around `cargo doc`.
684 fn run(self, builder: &Builder<'_>) {
685 let stage = self.stage;
686 let target = self.target;
689 "Documenting stage{} {} ({})",
691 stringify!($tool).to_lowercase(),
696 // This is the intended out directory for compiler documentation.
697 let out = builder.compiler_doc_out(target);
698 t!(fs::create_dir_all(&out));
700 let compiler = builder.compiler(stage, builder.config.build);
702 // Build rustc docs so that we generate relative links.
703 builder.ensure(Rustc { stage, target });
705 // Symlink compiler docs to the output directory of rustdoc documentation.
706 let out_dir = builder.stage_out(compiler, Mode::ToolRustc).join(target.triple).join("doc");
707 t!(fs::create_dir_all(&out_dir));
708 t!(symlink_dir_force(&builder.config, &out, &out_dir));
710 // Build cargo command.
711 let mut cargo = prepare_tool_cargo(
722 cargo.arg("-Zskip-rustdoc-fingerprint");
723 // Only include compiler crates, no dependencies of those, such as `libc`.
724 cargo.arg("--no-deps");
726 cargo.arg("-p").arg($krate);
729 cargo.rustdocflag("--document-private-items");
730 cargo.rustdocflag("--enable-index-page");
731 cargo.rustdocflag("--show-type-layout");
732 cargo.rustdocflag("--generate-link-to-definition");
733 cargo.rustdocflag("-Zunstable-options");
734 builder.run(&mut cargo.into());
740 tool_doc!(Rustdoc, "rustdoc-tool", "src/tools/rustdoc", ["rustdoc", "rustdoc-json-types"]);
745 ["rustfmt-nightly", "rustfmt-config_proc_macro"],
747 tool_doc!(Clippy, "clippy", "src/tools/clippy", ["clippy_utils"]);
749 #[derive(Ord, PartialOrd, Debug, Copy, Clone, Hash, PartialEq, Eq)]
750 pub struct ErrorIndex {
751 pub target: TargetSelection,
754 impl Step for ErrorIndex {
756 const DEFAULT: bool = true;
757 const ONLY_HOSTS: bool = true;
759 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
760 let builder = run.builder;
761 run.path("src/tools/error_index_generator").default_condition(builder.config.docs)
764 fn make_run(run: RunConfig<'_>) {
765 let target = run.target;
766 run.builder.ensure(ErrorIndex { target });
769 /// Generates the HTML rendered error-index by running the
770 /// `error_index_generator` tool.
771 fn run(self, builder: &Builder<'_>) {
772 builder.info(&format!("Documenting error index ({})", self.target));
773 let out = builder.doc_out(self.target);
774 t!(fs::create_dir_all(&out));
775 let mut index = tool::ErrorIndex::command(builder);
777 index.arg(out.join("error-index.html"));
778 index.arg(&builder.version);
780 builder.run(&mut index);
784 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
785 pub struct UnstableBookGen {
786 target: TargetSelection,
789 impl Step for UnstableBookGen {
791 const DEFAULT: bool = true;
792 const ONLY_HOSTS: bool = true;
794 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
795 let builder = run.builder;
796 run.path("src/tools/unstable-book-gen").default_condition(builder.config.docs)
799 fn make_run(run: RunConfig<'_>) {
800 run.builder.ensure(UnstableBookGen { target: run.target });
803 fn run(self, builder: &Builder<'_>) {
804 let target = self.target;
806 builder.info(&format!("Generating unstable book md files ({})", target));
807 let out = builder.md_doc_out(target).join("unstable-book");
808 builder.create_dir(&out);
809 builder.remove_dir(&out);
810 let mut cmd = builder.tool_cmd(Tool::UnstableBookGen);
811 cmd.arg(builder.src.join("library"));
812 cmd.arg(builder.src.join("compiler"));
813 cmd.arg(builder.src.join("src"));
816 builder.run(&mut cmd);
820 fn symlink_dir_force(config: &Config, src: &Path, dst: &Path) -> io::Result<()> {
824 if let Ok(m) = fs::symlink_metadata(dst) {
825 if m.file_type().is_dir() {
826 fs::remove_dir_all(dst)?;
828 // handle directory junctions on windows by falling back to
830 fs::remove_file(dst).or_else(|_| fs::remove_dir(dst))?;
834 symlink_dir(config, src, dst)
837 #[derive(Ord, PartialOrd, Debug, Copy, Clone, Hash, PartialEq, Eq)]
838 pub struct RustcBook {
839 pub compiler: Compiler,
840 pub target: TargetSelection,
844 impl Step for RustcBook {
846 const DEFAULT: bool = true;
847 const ONLY_HOSTS: bool = true;
849 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
850 let builder = run.builder;
851 run.path("src/doc/rustc").default_condition(builder.config.docs)
854 fn make_run(run: RunConfig<'_>) {
855 run.builder.ensure(RustcBook {
856 compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
862 /// Builds the rustc book.
864 /// The lints are auto-generated by a tool, and then merged into the book
865 /// in the "md-doc" directory in the build output directory. Then
866 /// "rustbook" is used to convert it to HTML.
867 fn run(self, builder: &Builder<'_>) {
868 let out_base = builder.md_doc_out(self.target).join("rustc");
869 t!(fs::create_dir_all(&out_base));
870 let out_listing = out_base.join("src/lints");
871 builder.cp_r(&builder.src.join("src/doc/rustc"), &out_base);
872 builder.info(&format!("Generating lint docs ({})", self.target));
874 let rustc = builder.rustc(self.compiler);
875 // The tool runs `rustc` for extracting output examples, so it needs a
876 // functional sysroot.
877 builder.ensure(compile::Std { compiler: self.compiler, target: self.target });
878 let mut cmd = builder.tool_cmd(Tool::LintDocs);
880 cmd.arg(builder.src.join("compiler"));
882 cmd.arg(&out_listing);
885 cmd.arg("--rustc-target").arg(&self.target.rustc_target_arg());
886 if builder.config.verbose() {
887 cmd.arg("--verbose");
890 cmd.arg("--validate");
892 // If the lib directories are in an unusual location (changed in
893 // config.toml), then this needs to explicitly update the dylib search
895 builder.add_rustc_lib_path(self.compiler, &mut cmd);
896 builder.run(&mut cmd);
897 // Run rustbook/mdbook to generate the HTML pages.
898 builder.ensure(RustbookSrc {
900 name: INTERNER.intern_str("rustc"),
901 src: INTERNER.intern_path(out_base),
903 if builder.was_invoked_explicitly::<Self>(Kind::Doc) {
904 let out = builder.doc_out(self.target);
905 let index = out.join("rustc").join("index.html");
906 open(builder, &index);