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};
16 use build_helper::{t, up_to_date};
18 use crate::builder::{Builder, Compiler, RunConfig, ShouldRun, Step};
19 use crate::cache::{Interned, INTERNER};
21 use crate::config::{Config, TargetSelection};
22 use crate::tool::{self, prepare_tool_cargo, SourceType, Tool};
23 use crate::util::symlink_dir;
25 macro_rules! submodule_helper {
26 ($path:expr, submodule) => {
29 ($path:expr, submodule = $submodule:literal) => {
35 ($($name:ident, $path:expr, $book_name:expr $(, submodule $(= $submodule:literal)? )? ;)+) => {
37 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
39 target: TargetSelection,
44 const DEFAULT: bool = true;
46 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
47 let builder = run.builder;
48 run.path($path).default_condition(builder.config.docs)
51 fn make_run(run: RunConfig<'_>) {
52 run.builder.ensure($name {
57 fn run(self, builder: &Builder<'_>) {
59 let path = Path::new(submodule_helper!( $path, submodule $( = $submodule )? ));
60 builder.update_submodule(&path);
62 builder.ensure(RustbookSrc {
64 name: INTERNER.intern_str($book_name),
65 src: INTERNER.intern_path(builder.src.join($path)),
73 // NOTE: When adding a book here, make sure to ALSO build the book by
74 // adding a build step in `src/bootstrap/builder.rs`!
75 // NOTE: Make sure to add the corresponding submodule when adding a new book.
76 // FIXME: Make checking for a submodule automatic somehow (maybe by having a list of all submodules
77 // and checking against it?).
79 CargoBook, "src/tools/cargo/src/doc", "cargo", submodule = "src/tools/cargo";
80 EditionGuide, "src/doc/edition-guide", "edition-guide", submodule;
81 EmbeddedBook, "src/doc/embedded-book", "embedded-book", submodule;
82 Nomicon, "src/doc/nomicon", "nomicon", submodule;
83 Reference, "src/doc/reference", "reference", submodule;
84 RustByExample, "src/doc/rust-by-example", "rust-by-example", submodule;
85 RustdocBook, "src/doc/rustdoc", "rustdoc";
88 fn open(builder: &Builder<'_>, path: impl AsRef<Path>) {
89 if builder.config.dry_run || !builder.config.cmd.open() {
93 let path = path.as_ref();
94 builder.info(&format!("Opening doc {}", path.display()));
95 if let Err(err) = opener::open(path) {
96 builder.info(&format!("{}\n", err));
100 // "library/std" -> ["library", "std"]
102 // Used for deciding whether a particular step is one requested by the user on
103 // the `x.py doc` command line, which determines whether `--open` will open that
105 pub(crate) fn components_simplified(path: &PathBuf) -> Vec<&str> {
106 path.iter().map(|component| component.to_str().unwrap_or("???")).collect()
109 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
110 pub struct UnstableBook {
111 target: TargetSelection,
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 { target: run.target });
127 fn run(self, builder: &Builder<'_>) {
128 builder.ensure(UnstableBookGen { target: self.target });
129 builder.ensure(RustbookSrc {
131 name: INTERNER.intern_str("unstable-book"),
132 src: INTERNER.intern_path(builder.md_doc_out(self.target).join("unstable-book")),
137 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
139 target: TargetSelection,
140 name: Interned<String>,
141 src: Interned<PathBuf>,
144 impl Step for RustbookSrc {
147 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
151 /// Invoke `rustbook` for `target` for the doc book `name` from the `src` path.
153 /// This will not actually generate any documentation if the documentation has
154 /// already been generated.
155 fn run(self, builder: &Builder<'_>) {
156 let target = self.target;
157 let name = self.name;
159 let out = builder.doc_out(target);
160 t!(fs::create_dir_all(&out));
162 let out = out.join(name);
163 let index = out.join("index.html");
164 let rustbook = builder.tool_exe(Tool::Rustbook);
165 let mut rustbook_cmd = builder.tool_cmd(Tool::Rustbook);
166 if builder.config.dry_run || up_to_date(&src, &index) && up_to_date(&rustbook, &index) {
169 builder.info(&format!("Rustbook ({}) - {}", target, name));
170 let _ = fs::remove_dir_all(&out);
172 builder.run(rustbook_cmd.arg("build").arg(&src).arg("-d").arg(out));
176 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
179 target: TargetSelection,
182 impl Step for TheBook {
184 const DEFAULT: bool = true;
186 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
187 let builder = run.builder;
188 run.path("src/doc/book").default_condition(builder.config.docs)
191 fn make_run(run: RunConfig<'_>) {
192 run.builder.ensure(TheBook {
193 compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
198 /// Builds the book and associated stuff.
200 /// We need to build:
203 /// * Older edition redirects
204 /// * Version info and CSS
207 fn run(self, builder: &Builder<'_>) {
208 let relative_path = Path::new("src").join("doc").join("book");
209 builder.update_submodule(&relative_path);
211 let compiler = self.compiler;
212 let target = self.target;
215 builder.ensure(RustbookSrc {
217 name: INTERNER.intern_str("book"),
218 src: INTERNER.intern_path(builder.src.join(&relative_path)),
221 // building older edition redirects
222 for edition in &["first-edition", "second-edition", "2018-edition"] {
223 builder.ensure(RustbookSrc {
225 name: INTERNER.intern_string(format!("book/{}", edition)),
226 src: INTERNER.intern_path(builder.src.join(&relative_path).join(edition)),
230 // build the version info page and CSS
231 builder.ensure(Standalone { compiler, target });
233 // build the redirect pages
234 builder.info(&format!("Documenting book redirect pages ({})", target));
235 for file in t!(fs::read_dir(builder.src.join(&relative_path).join("redirects"))) {
237 let path = file.path();
238 let path = path.to_str().unwrap();
240 invoke_rustdoc(builder, compiler, target, path);
243 if builder.was_invoked_explicitly::<Self>() {
244 let out = builder.doc_out(target);
245 let index = out.join("book").join("index.html");
246 open(builder, &index);
252 builder: &Builder<'_>,
254 target: TargetSelection,
257 let out = builder.doc_out(target);
259 let path = builder.src.join("src/doc").join(markdown);
261 let header = builder.src.join("src/doc/redirect.inc");
262 let footer = builder.src.join("src/doc/footer.inc");
263 let version_info = out.join("version_info.html");
265 let mut cmd = builder.rustdoc_cmd(compiler);
267 let out = out.join("book");
269 cmd.arg("--html-after-content")
271 .arg("--html-before-content")
273 .arg("--html-in-header")
275 .arg("--markdown-no-toc")
276 .arg("--markdown-playground-url")
277 .arg("https://play.rust-lang.org/")
281 .arg("--markdown-css")
284 if !builder.config.docs_minification {
285 cmd.arg("-Z").arg("unstable-options").arg("--disable-minification");
288 builder.run(&mut cmd);
291 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
292 pub struct Standalone {
294 target: TargetSelection,
297 impl Step for Standalone {
299 const DEFAULT: bool = true;
301 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
302 let builder = run.builder;
303 run.path("src/doc").default_condition(builder.config.docs)
306 fn make_run(run: RunConfig<'_>) {
307 run.builder.ensure(Standalone {
308 compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
313 /// Generates all standalone documentation as compiled by the rustdoc in `stage`
314 /// for the `target` into `out`.
316 /// This will list all of `src/doc` looking for markdown files and appropriately
317 /// perform transformations like substituting `VERSION`, `SHORT_HASH`, and
318 /// `STAMP` along with providing the various header/footer HTML we've customized.
320 /// In the end, this is just a glorified wrapper around rustdoc!
321 fn run(self, builder: &Builder<'_>) {
322 let target = self.target;
323 let compiler = self.compiler;
324 builder.info(&format!("Documenting standalone ({})", target));
325 let out = builder.doc_out(target);
326 t!(fs::create_dir_all(&out));
328 let favicon = builder.src.join("src/doc/favicon.inc");
329 let footer = builder.src.join("src/doc/footer.inc");
330 let full_toc = builder.src.join("src/doc/full-toc.inc");
331 t!(fs::copy(builder.src.join("src/doc/rust.css"), out.join("rust.css")));
333 let version_input = builder.src.join("src/doc/version_info.html.template");
334 let version_info = out.join("version_info.html");
336 if !builder.config.dry_run && !up_to_date(&version_input, &version_info) {
337 let info = t!(fs::read_to_string(&version_input))
338 .replace("VERSION", &builder.rust_release())
339 .replace("SHORT_HASH", builder.rust_info.sha_short().unwrap_or(""))
340 .replace("STAMP", builder.rust_info.sha().unwrap_or(""));
341 t!(fs::write(&version_info, &info));
344 for file in t!(fs::read_dir(builder.src.join("src/doc"))) {
346 let path = file.path();
347 let filename = path.file_name().unwrap().to_str().unwrap();
348 if !filename.ends_with(".md") || filename == "README.md" {
352 let html = out.join(filename).with_extension("html");
353 let rustdoc = builder.rustdoc(compiler);
354 if up_to_date(&path, &html)
355 && up_to_date(&footer, &html)
356 && up_to_date(&favicon, &html)
357 && up_to_date(&full_toc, &html)
358 && (builder.config.dry_run || up_to_date(&version_info, &html))
359 && (builder.config.dry_run || up_to_date(&rustdoc, &html))
364 let mut cmd = builder.rustdoc_cmd(compiler);
365 // Needed for --index-page flag
366 cmd.arg("-Z").arg("unstable-options");
368 cmd.arg("--html-after-content")
370 .arg("--html-before-content")
372 .arg("--html-in-header")
374 .arg("--markdown-no-toc")
376 .arg(&builder.src.join("src/doc/index.md"))
377 .arg("--markdown-playground-url")
378 .arg("https://play.rust-lang.org/")
383 if !builder.config.docs_minification {
384 cmd.arg("--disable-minification");
387 if filename == "not_found.md" {
388 cmd.arg("--markdown-css")
389 .arg(format!("https://doc.rust-lang.org/rustdoc{}.css", &builder.version))
390 .arg("--markdown-css")
391 .arg("https://doc.rust-lang.org/rust.css");
393 cmd.arg("--markdown-css")
394 .arg(format!("rustdoc{}.css", &builder.version))
395 .arg("--markdown-css")
398 builder.run(&mut cmd);
401 // We open doc/index.html as the default if invoked as `x.py doc --open`
402 // with no particular explicit doc requested (e.g. library/core).
403 if builder.paths.is_empty() || builder.was_invoked_explicitly::<Self>() {
404 let index = out.join("index.html");
405 open(builder, &index);
410 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
413 pub target: TargetSelection,
418 const DEFAULT: bool = true;
420 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
421 let builder = run.builder;
422 run.all_krates("test").default_condition(builder.config.docs)
425 fn make_run(run: RunConfig<'_>) {
426 run.builder.ensure(Std { stage: run.builder.top_stage, target: run.target });
429 /// Compile all standard library documentation.
431 /// This will generate all documentation for the standard library and its
432 /// dependencies. This is largely just a wrapper around `cargo doc`.
433 fn run(self, builder: &Builder<'_>) {
434 let stage = self.stage;
435 let target = self.target;
436 builder.info(&format!("Documenting stage{} std ({})", stage, target));
437 let out = builder.doc_out(target);
438 t!(fs::create_dir_all(&out));
439 let compiler = builder.compiler(stage, builder.config.build);
441 builder.ensure(compile::Std { compiler, target });
442 let out_dir = builder.stage_out(compiler, Mode::Std).join(target.triple).join("doc");
444 t!(fs::copy(builder.src.join("src/doc/rust.css"), out.join("rust.css")));
446 let run_cargo_rustdoc_for = |package: &str| {
448 builder.cargo(compiler, Mode::Std, SourceType::InTree, target, "rustdoc");
449 compile::std_cargo(builder, target, compiler.stage, &mut cargo);
454 .arg("-Zskip-rustdoc-fingerprint")
456 .arg("--markdown-css")
458 .arg("--markdown-no-toc")
460 .arg("unstable-options")
461 .arg("--resource-suffix")
462 .arg(&builder.version)
464 .arg(&builder.src.join("src/doc/index.md"));
466 if !builder.config.docs_minification {
467 cargo.arg("--disable-minification");
470 builder.run(&mut cargo.into());
476 .map(components_simplified)
478 if path.get(0) == Some(&"library") {
479 Some(path[1].to_owned())
480 } else if !path.is_empty() {
481 Some(path[0].to_owned())
486 .collect::<Vec<_>>();
488 // Only build the following crates. While we could just iterate over the
489 // folder structure, that would also build internal crates that we do
490 // not want to show in documentation. These crates will later be visited
491 // by the rustc step, so internal documentation will show them.
493 // Note that the order here is important! The crates need to be
494 // processed starting from the leaves, otherwise rustdoc will not
495 // create correct links between crates because rustdoc depends on the
496 // existence of the output directories to know if it should be a local
498 let krates = ["core", "alloc", "std", "proc_macro", "test"];
499 for krate in &krates {
500 run_cargo_rustdoc_for(krate);
501 if paths.iter().any(|p| p == krate) {
502 // No need to document more of the libraries if we have the one we want.
506 builder.cp_r(&out_dir, &out);
508 // Look for library/std, library/core etc in the `x.py doc` arguments and
509 // open the corresponding rendered docs.
510 for requested_crate in paths {
511 if krates.iter().any(|k| *k == requested_crate.as_str()) {
512 let index = out.join(requested_crate).join("index.html");
513 open(builder, &index);
519 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
522 pub target: TargetSelection,
525 impl Step for Rustc {
527 const DEFAULT: bool = true;
528 const ONLY_HOSTS: bool = true;
530 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
531 let builder = run.builder;
532 run.krate("rustc-main").path("compiler").default_condition(builder.config.docs)
535 fn make_run(run: RunConfig<'_>) {
536 run.builder.ensure(Rustc { stage: run.builder.top_stage, target: run.target });
539 /// Generates compiler documentation.
541 /// This will generate all documentation for compiler and dependencies.
542 /// Compiler documentation is distributed separately, so we make sure
543 /// we do not merge it with the other documentation from std, test and
544 /// proc_macros. This is largely just a wrapper around `cargo doc`.
545 fn run(self, builder: &Builder<'_>) {
546 let stage = self.stage;
547 let target = self.target;
548 builder.info(&format!("Documenting stage{} compiler ({})", stage, target));
553 .map(components_simplified)
555 if path.get(0) == Some(&"compiler") {
556 path.get(1).map(|p| p.to_owned())
561 .collect::<Vec<_>>();
563 if !builder.config.compiler_docs && !builder.was_invoked_explicitly::<Self>() {
564 builder.info("\tskipping - compiler/librustdoc docs disabled");
568 // This is the intended out directory for compiler documentation.
569 let out = builder.compiler_doc_out(target);
570 t!(fs::create_dir_all(&out));
573 let compiler = builder.compiler(stage, builder.config.build);
574 builder.ensure(compile::Rustc { compiler, target });
576 // This uses a shared directory so that librustdoc documentation gets
577 // correctly built and merged with the rustc documentation. This is
578 // needed because rustdoc is built in a different directory from
579 // rustc. rustdoc needs to be able to see everything, for example when
580 // merging the search index, or generating local (relative) links.
581 let out_dir = builder.stage_out(compiler, Mode::Rustc).join(target.triple).join("doc");
582 t!(symlink_dir_force(&builder.config, &out, &out_dir));
583 // Cargo puts proc macros in `target/doc` even if you pass `--target`
584 // explicitly (https://github.com/rust-lang/cargo/issues/7677).
585 let proc_macro_out_dir = builder.stage_out(compiler, Mode::Rustc).join("doc");
586 t!(symlink_dir_force(&builder.config, &out, &proc_macro_out_dir));
588 // Build cargo command.
589 let mut cargo = builder.cargo(compiler, Mode::Rustc, SourceType::InTree, target, "doc");
590 cargo.rustdocflag("--document-private-items");
591 // Since we always pass --document-private-items, there's no need to warn about linking to private items.
592 cargo.rustdocflag("-Arustdoc::private-intra-doc-links");
593 cargo.rustdocflag("--enable-index-page");
594 cargo.rustdocflag("-Zunstable-options");
595 cargo.rustdocflag("-Znormalize-docs");
596 cargo.rustdocflag("--show-type-layout");
597 cargo.rustdocflag("--generate-link-to-definition");
598 compile::rustc_cargo(builder, &mut cargo, target);
599 cargo.arg("-Zunstable-options");
600 cargo.arg("-Zskip-rustdoc-fingerprint");
602 // Only include compiler crates, no dependencies of those, such as `libc`.
603 // Do link to dependencies on `docs.rs` however using `rustdoc-map`.
604 cargo.arg("--no-deps");
605 cargo.arg("-Zrustdoc-map");
607 // FIXME: `-Zrustdoc-map` does not yet correctly work for transitive dependencies,
608 // once this is no longer an issue the special case for `ena` can be removed.
609 cargo.rustdocflag("--extern-html-root-url");
610 cargo.rustdocflag("ena=https://docs.rs/ena/latest/");
612 let mut compiler_crates = HashSet::new();
614 if paths.is_empty() {
615 // Find dependencies for top level crates.
616 for root_crate in &["rustc_driver", "rustc_codegen_llvm", "rustc_codegen_ssa"] {
617 compiler_crates.extend(
619 .in_tree_crates(root_crate, Some(target))
621 .map(|krate| krate.name),
625 for root_crate in paths {
626 if !builder.src.join("compiler").join(&root_crate).exists() {
627 builder.info(&format!(
628 "\tskipping - compiler/{} (unknown compiler crate)",
632 compiler_crates.extend(
634 .in_tree_crates(root_crate, Some(target))
636 .map(|krate| krate.name),
642 let mut to_open = None;
643 for krate in &compiler_crates {
644 // Create all crate output directories first to make sure rustdoc uses
646 // FIXME: Cargo should probably do this itself.
647 t!(fs::create_dir_all(out_dir.join(krate)));
648 cargo.arg("-p").arg(krate);
649 if to_open.is_none() {
650 to_open = Some(krate);
654 builder.run(&mut cargo.into());
655 // Let's open the first crate documentation page:
656 if let Some(krate) = to_open {
657 let index = out.join(krate).join("index.html");
658 open(builder, &index);
663 macro_rules! tool_doc {
664 ($tool: ident, $should_run: literal, $path: literal, [$($krate: literal),+ $(,)?] $(,)?) => {
665 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
668 target: TargetSelection,
671 impl Step for $tool {
673 const DEFAULT: bool = true;
674 const ONLY_HOSTS: bool = true;
676 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
677 run.krate($should_run)
680 fn make_run(run: RunConfig<'_>) {
681 run.builder.ensure($tool { stage: run.builder.top_stage, target: run.target });
684 /// Generates compiler documentation.
686 /// This will generate all documentation for compiler and dependencies.
687 /// Compiler documentation is distributed separately, so we make sure
688 /// we do not merge it with the other documentation from std, test and
689 /// proc_macros. This is largely just a wrapper around `cargo doc`.
690 fn run(self, builder: &Builder<'_>) {
691 let stage = self.stage;
692 let target = self.target;
695 "Documenting stage{} {} ({})",
697 stringify!($tool).to_lowercase(),
702 // This is the intended out directory for compiler documentation.
703 let out = builder.compiler_doc_out(target);
704 t!(fs::create_dir_all(&out));
706 let compiler = builder.compiler(stage, builder.config.build);
708 if !builder.config.compiler_docs && !builder.was_invoked_explicitly::<Self>() {
709 builder.info("\tskipping - compiler/tool docs disabled");
713 // Build rustc docs so that we generate relative links.
714 builder.ensure(Rustc { stage, target });
716 // Symlink compiler docs to the output directory of rustdoc documentation.
717 let out_dir = builder.stage_out(compiler, Mode::ToolRustc).join(target.triple).join("doc");
718 t!(fs::create_dir_all(&out_dir));
719 t!(symlink_dir_force(&builder.config, &out, &out_dir));
721 // Build cargo command.
722 let mut cargo = prepare_tool_cargo(
733 cargo.arg("-Zskip-rustdoc-fingerprint");
734 // Only include compiler crates, no dependencies of those, such as `libc`.
735 cargo.arg("--no-deps");
737 cargo.arg("-p").arg($krate);
740 cargo.rustdocflag("--document-private-items");
741 cargo.rustdocflag("--enable-index-page");
742 cargo.rustdocflag("--show-type-layout");
743 cargo.rustdocflag("--generate-link-to-definition");
744 cargo.rustdocflag("-Zunstable-options");
745 builder.run(&mut cargo.into());
751 tool_doc!(Rustdoc, "rustdoc-tool", "src/tools/rustdoc", ["rustdoc", "rustdoc-json-types"]);
756 ["rustfmt-nightly", "rustfmt-config_proc_macro"],
758 tool_doc!(Clippy, "clippy", "src/tools/clippy", ["clippy_utils"]);
760 #[derive(Ord, PartialOrd, Debug, Copy, Clone, Hash, PartialEq, Eq)]
761 pub struct ErrorIndex {
762 pub target: TargetSelection,
765 impl Step for ErrorIndex {
767 const DEFAULT: bool = true;
768 const ONLY_HOSTS: bool = true;
770 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
771 let builder = run.builder;
772 run.path("src/tools/error_index_generator").default_condition(builder.config.docs)
775 fn make_run(run: RunConfig<'_>) {
776 let target = run.target;
777 run.builder.ensure(ErrorIndex { target });
780 /// Generates the HTML rendered error-index by running the
781 /// `error_index_generator` tool.
782 fn run(self, builder: &Builder<'_>) {
783 builder.info(&format!("Documenting error index ({})", self.target));
784 let out = builder.doc_out(self.target);
785 t!(fs::create_dir_all(&out));
786 let mut index = tool::ErrorIndex::command(builder);
788 index.arg(out.join("error-index.html"));
789 index.arg(&builder.version);
791 builder.run(&mut index);
795 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
796 pub struct UnstableBookGen {
797 target: TargetSelection,
800 impl Step for UnstableBookGen {
802 const DEFAULT: bool = true;
803 const ONLY_HOSTS: bool = true;
805 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
806 let builder = run.builder;
807 run.path("src/tools/unstable-book-gen").default_condition(builder.config.docs)
810 fn make_run(run: RunConfig<'_>) {
811 run.builder.ensure(UnstableBookGen { target: run.target });
814 fn run(self, builder: &Builder<'_>) {
815 let target = self.target;
817 builder.info(&format!("Generating unstable book md files ({})", target));
818 let out = builder.md_doc_out(target).join("unstable-book");
819 builder.create_dir(&out);
820 builder.remove_dir(&out);
821 let mut cmd = builder.tool_cmd(Tool::UnstableBookGen);
822 cmd.arg(builder.src.join("library"));
823 cmd.arg(builder.src.join("compiler"));
824 cmd.arg(builder.src.join("src"));
827 builder.run(&mut cmd);
831 fn symlink_dir_force(config: &Config, src: &Path, dst: &Path) -> io::Result<()> {
835 if let Ok(m) = fs::symlink_metadata(dst) {
836 if m.file_type().is_dir() {
837 fs::remove_dir_all(dst)?;
839 // handle directory junctions on windows by falling back to
841 fs::remove_file(dst).or_else(|_| fs::remove_dir(dst))?;
845 symlink_dir(config, src, dst)
848 #[derive(Ord, PartialOrd, Debug, Copy, Clone, Hash, PartialEq, Eq)]
849 pub struct RustcBook {
850 pub compiler: Compiler,
851 pub target: TargetSelection,
855 impl Step for RustcBook {
857 const DEFAULT: bool = true;
858 const ONLY_HOSTS: bool = true;
860 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
861 let builder = run.builder;
862 run.path("src/doc/rustc").default_condition(builder.config.docs)
865 fn make_run(run: RunConfig<'_>) {
866 run.builder.ensure(RustcBook {
867 compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
873 /// Builds the rustc book.
875 /// The lints are auto-generated by a tool, and then merged into the book
876 /// in the "md-doc" directory in the build output directory. Then
877 /// "rustbook" is used to convert it to HTML.
878 fn run(self, builder: &Builder<'_>) {
879 let out_base = builder.md_doc_out(self.target).join("rustc");
880 t!(fs::create_dir_all(&out_base));
881 let out_listing = out_base.join("src/lints");
882 builder.cp_r(&builder.src.join("src/doc/rustc"), &out_base);
883 builder.info(&format!("Generating lint docs ({})", self.target));
885 let rustc = builder.rustc(self.compiler);
886 // The tool runs `rustc` for extracting output examples, so it needs a
887 // functional sysroot.
888 builder.ensure(compile::Std { compiler: self.compiler, target: self.target });
889 let mut cmd = builder.tool_cmd(Tool::LintDocs);
891 cmd.arg(builder.src.join("compiler"));
893 cmd.arg(&out_listing);
896 cmd.arg("--rustc-target").arg(&self.target.rustc_target_arg());
897 if builder.config.verbose() {
898 cmd.arg("--verbose");
901 cmd.arg("--validate");
903 // If the lib directories are in an unusual location (changed in
904 // config.toml), then this needs to explicitly update the dylib search
906 builder.add_rustc_lib_path(self.compiler, &mut cmd);
907 builder.run(&mut cmd);
908 // Run rustbook/mdbook to generate the HTML pages.
909 builder.ensure(RustbookSrc {
911 name: INTERNER.intern_str("rustc"),
912 src: INTERNER.intern_path(out_base),
914 if builder.was_invoked_explicitly::<Self>() {
915 let out = builder.doc_out(self.target);
916 let index = out.join("rustc").join("index.html");
917 open(builder, &index);