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
12 use std::path::{Path, PathBuf};
14 use crate::builder::{Builder, Compiler, Kind, RunConfig, ShouldRun, Step};
15 use crate::cache::{Interned, INTERNER};
17 use crate::config::{Config, TargetSelection};
18 use crate::tool::{self, prepare_tool_cargo, SourceType, Tool};
19 use crate::util::{symlink_dir, t, up_to_date};
22 macro_rules! submodule_helper {
23 ($path:expr, submodule) => {
26 ($path:expr, submodule = $submodule:literal) => {
32 ($($name:ident, $path:expr, $book_name:expr $(, submodule $(= $submodule:literal)? )? ;)+) => {
34 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
36 target: TargetSelection,
41 const DEFAULT: bool = true;
43 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
44 let builder = run.builder;
45 run.path($path).default_condition(builder.config.docs)
48 fn make_run(run: RunConfig<'_>) {
49 run.builder.ensure($name {
54 fn run(self, builder: &Builder<'_>) {
56 let path = Path::new(submodule_helper!( $path, submodule $( = $submodule )? ));
57 builder.update_submodule(&path);
59 builder.ensure(RustbookSrc {
61 name: INTERNER.intern_str($book_name),
62 src: INTERNER.intern_path(builder.src.join($path)),
70 // NOTE: When adding a book here, make sure to ALSO build the book by
71 // adding a build step in `src/bootstrap/builder.rs`!
72 // NOTE: Make sure to add the corresponding submodule when adding a new book.
73 // FIXME: Make checking for a submodule automatic somehow (maybe by having a list of all submodules
74 // and checking against it?).
76 CargoBook, "src/tools/cargo/src/doc", "cargo", submodule = "src/tools/cargo";
77 EditionGuide, "src/doc/edition-guide", "edition-guide", submodule;
78 EmbeddedBook, "src/doc/embedded-book", "embedded-book", submodule;
79 Nomicon, "src/doc/nomicon", "nomicon", submodule;
80 Reference, "src/doc/reference", "reference", submodule;
81 RustByExample, "src/doc/rust-by-example", "rust-by-example", submodule;
82 RustdocBook, "src/doc/rustdoc", "rustdoc";
85 fn open(builder: &Builder<'_>, path: impl AsRef<Path>) {
86 if builder.config.dry_run || !builder.config.cmd.open() {
90 let path = path.as_ref();
91 builder.info(&format!("Opening doc {}", path.display()));
92 if let Err(err) = opener::open(path) {
93 builder.info(&format!("{}\n", err));
97 // "library/std" -> ["library", "std"]
99 // Used for deciding whether a particular step is one requested by the user on
100 // the `x.py doc` command line, which determines whether `--open` will open that
102 pub(crate) fn components_simplified(path: &PathBuf) -> Vec<&str> {
103 path.iter().map(|component| component.to_str().unwrap_or("???")).collect()
106 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
107 pub struct UnstableBook {
108 target: TargetSelection,
111 impl Step for UnstableBook {
113 const DEFAULT: bool = true;
115 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
116 let builder = run.builder;
117 run.path("src/doc/unstable-book").default_condition(builder.config.docs)
120 fn make_run(run: RunConfig<'_>) {
121 run.builder.ensure(UnstableBook { target: run.target });
124 fn run(self, builder: &Builder<'_>) {
125 builder.ensure(UnstableBookGen { target: self.target });
126 builder.ensure(RustbookSrc {
128 name: INTERNER.intern_str("unstable-book"),
129 src: INTERNER.intern_path(builder.md_doc_out(self.target).join("unstable-book")),
134 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
136 target: TargetSelection,
137 name: Interned<String>,
138 src: Interned<PathBuf>,
141 impl Step for RustbookSrc {
144 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
148 /// Invoke `rustbook` for `target` for the doc book `name` from the `src` path.
150 /// This will not actually generate any documentation if the documentation has
151 /// already been generated.
152 fn run(self, builder: &Builder<'_>) {
153 let target = self.target;
154 let name = self.name;
156 let out = builder.doc_out(target);
157 t!(fs::create_dir_all(&out));
159 let out = out.join(name);
160 let index = out.join("index.html");
161 let rustbook = builder.tool_exe(Tool::Rustbook);
162 let mut rustbook_cmd = builder.tool_cmd(Tool::Rustbook);
163 if builder.config.dry_run || up_to_date(&src, &index) && up_to_date(&rustbook, &index) {
166 builder.info(&format!("Rustbook ({}) - {}", target, name));
167 let _ = fs::remove_dir_all(&out);
169 builder.run(rustbook_cmd.arg("build").arg(&src).arg("-d").arg(out));
173 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
176 target: TargetSelection,
179 impl Step for TheBook {
181 const DEFAULT: bool = true;
183 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
184 let builder = run.builder;
185 run.path("src/doc/book").default_condition(builder.config.docs)
188 fn make_run(run: RunConfig<'_>) {
189 run.builder.ensure(TheBook {
190 compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
195 /// Builds the book and associated stuff.
197 /// We need to build:
200 /// * Older edition redirects
201 /// * Version info and CSS
204 fn run(self, builder: &Builder<'_>) {
205 let relative_path = Path::new("src").join("doc").join("book");
206 builder.update_submodule(&relative_path);
208 let compiler = self.compiler;
209 let target = self.target;
212 builder.ensure(RustbookSrc {
214 name: INTERNER.intern_str("book"),
215 src: INTERNER.intern_path(builder.src.join(&relative_path)),
218 // building older edition redirects
219 for edition in &["first-edition", "second-edition", "2018-edition"] {
220 builder.ensure(RustbookSrc {
222 name: INTERNER.intern_string(format!("book/{}", edition)),
223 src: INTERNER.intern_path(builder.src.join(&relative_path).join(edition)),
227 // build the version info page and CSS
228 builder.ensure(Standalone { compiler, target });
230 // build the redirect pages
231 builder.info(&format!("Documenting book redirect pages ({})", target));
232 for file in t!(fs::read_dir(builder.src.join(&relative_path).join("redirects"))) {
234 let path = file.path();
235 let path = path.to_str().unwrap();
237 invoke_rustdoc(builder, compiler, target, path);
240 if builder.was_invoked_explicitly::<Self>(Kind::Doc) {
241 let out = builder.doc_out(target);
242 let index = out.join("book").join("index.html");
243 open(builder, &index);
249 builder: &Builder<'_>,
251 target: TargetSelection,
254 let out = builder.doc_out(target);
256 let path = builder.src.join("src/doc").join(markdown);
258 let header = builder.src.join("src/doc/redirect.inc");
259 let footer = builder.src.join("src/doc/footer.inc");
260 let version_info = out.join("version_info.html");
262 let mut cmd = builder.rustdoc_cmd(compiler);
264 let out = out.join("book");
266 cmd.arg("--html-after-content")
268 .arg("--html-before-content")
270 .arg("--html-in-header")
272 .arg("--markdown-no-toc")
273 .arg("--markdown-playground-url")
274 .arg("https://play.rust-lang.org/")
278 .arg("--markdown-css")
281 if !builder.config.docs_minification {
282 cmd.arg("-Z").arg("unstable-options").arg("--disable-minification");
285 builder.run(&mut cmd);
288 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
289 pub struct Standalone {
291 target: TargetSelection,
294 impl Step for Standalone {
296 const DEFAULT: bool = true;
298 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
299 let builder = run.builder;
300 run.path("src/doc").default_condition(builder.config.docs)
303 fn make_run(run: RunConfig<'_>) {
304 run.builder.ensure(Standalone {
305 compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
310 /// Generates all standalone documentation as compiled by the rustdoc in `stage`
311 /// for the `target` into `out`.
313 /// This will list all of `src/doc` looking for markdown files and appropriately
314 /// perform transformations like substituting `VERSION`, `SHORT_HASH`, and
315 /// `STAMP` along with providing the various header/footer HTML we've customized.
317 /// In the end, this is just a glorified wrapper around rustdoc!
318 fn run(self, builder: &Builder<'_>) {
319 let target = self.target;
320 let compiler = self.compiler;
321 builder.info(&format!("Documenting standalone ({})", target));
322 let out = builder.doc_out(target);
323 t!(fs::create_dir_all(&out));
325 let favicon = builder.src.join("src/doc/favicon.inc");
326 let footer = builder.src.join("src/doc/footer.inc");
327 let full_toc = builder.src.join("src/doc/full-toc.inc");
328 t!(fs::copy(builder.src.join("src/doc/rust.css"), out.join("rust.css")));
330 let version_input = builder.src.join("src/doc/version_info.html.template");
331 let version_info = out.join("version_info.html");
333 if !builder.config.dry_run && !up_to_date(&version_input, &version_info) {
334 let info = t!(fs::read_to_string(&version_input))
335 .replace("VERSION", &builder.rust_release())
336 .replace("SHORT_HASH", builder.rust_info.sha_short().unwrap_or(""))
337 .replace("STAMP", builder.rust_info.sha().unwrap_or(""));
338 t!(fs::write(&version_info, &info));
341 for file in t!(fs::read_dir(builder.src.join("src/doc"))) {
343 let path = file.path();
344 let filename = path.file_name().unwrap().to_str().unwrap();
345 if !filename.ends_with(".md") || filename == "README.md" {
349 let html = out.join(filename).with_extension("html");
350 let rustdoc = builder.rustdoc(compiler);
351 if up_to_date(&path, &html)
352 && up_to_date(&footer, &html)
353 && up_to_date(&favicon, &html)
354 && up_to_date(&full_toc, &html)
355 && (builder.config.dry_run || up_to_date(&version_info, &html))
356 && (builder.config.dry_run || up_to_date(&rustdoc, &html))
361 let mut cmd = builder.rustdoc_cmd(compiler);
362 // Needed for --index-page flag
363 cmd.arg("-Z").arg("unstable-options");
365 cmd.arg("--html-after-content")
367 .arg("--html-before-content")
369 .arg("--html-in-header")
371 .arg("--markdown-no-toc")
373 .arg(&builder.src.join("src/doc/index.md"))
374 .arg("--markdown-playground-url")
375 .arg("https://play.rust-lang.org/")
380 if !builder.config.docs_minification {
381 cmd.arg("--disable-minification");
384 if filename == "not_found.md" {
385 cmd.arg("--markdown-css")
386 .arg(format!("https://doc.rust-lang.org/rustdoc{}.css", &builder.version))
387 .arg("--markdown-css")
388 .arg("https://doc.rust-lang.org/rust.css");
390 cmd.arg("--markdown-css")
391 .arg(format!("rustdoc{}.css", &builder.version))
392 .arg("--markdown-css")
395 builder.run(&mut cmd);
398 // We open doc/index.html as the default if invoked as `x.py doc --open`
399 // with no particular explicit doc requested (e.g. library/core).
400 if builder.paths.is_empty() || builder.was_invoked_explicitly::<Self>(Kind::Doc) {
401 let index = out.join("index.html");
402 open(builder, &index);
407 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
410 pub target: TargetSelection,
415 const DEFAULT: bool = true;
417 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
418 let builder = run.builder;
419 run.all_krates("test").path("library").default_condition(builder.config.docs)
422 fn make_run(run: RunConfig<'_>) {
423 run.builder.ensure(Std { stage: run.builder.top_stage, target: run.target });
426 /// Compile all standard library documentation.
428 /// This will generate all documentation for the standard library and its
429 /// dependencies. This is largely just a wrapper around `cargo doc`.
430 fn run(self, builder: &Builder<'_>) {
431 let stage = self.stage;
432 let target = self.target;
433 builder.info(&format!("Documenting stage{} std ({})", stage, target));
434 if builder.no_std(target) == Some(true) {
436 "building std documentation for no_std target {target} is not supported\n\
437 Set `docs = false` in the config to disable documentation."
440 let out = builder.doc_out(target);
441 t!(fs::create_dir_all(&out));
442 let compiler = builder.compiler(stage, builder.config.build);
444 let out_dir = builder.stage_out(compiler, Mode::Std).join(target.triple).join("doc");
446 t!(fs::copy(builder.src.join("src/doc/rust.css"), out.join("rust.css")));
448 let run_cargo_rustdoc_for = |package: &str| {
450 builder.cargo(compiler, Mode::Std, SourceType::InTree, target, "rustdoc");
451 compile::std_cargo(builder, target, compiler.stage, &mut cargo);
456 .arg("-Zskip-rustdoc-fingerprint")
458 .arg("--markdown-css")
460 .arg("--markdown-no-toc")
462 .arg("unstable-options")
463 .arg("--resource-suffix")
464 .arg(&builder.version)
466 .arg(&builder.src.join("src/doc/index.md"));
468 if !builder.config.docs_minification {
469 cargo.arg("--disable-minification");
472 builder.run(&mut cargo.into());
478 .map(components_simplified)
480 if path.len() >= 2 && path.get(0) == Some(&"library") {
482 Some(path[1].to_owned())
483 } else if !path.is_empty() {
485 Some(path[0].to_owned())
487 // all library crates
491 .collect::<Vec<_>>();
493 // Only build the following crates. While we could just iterate over the
494 // folder structure, that would also build internal crates that we do
495 // not want to show in documentation. These crates will later be visited
496 // by the rustc step, so internal documentation will show them.
498 // Note that the order here is important! The crates need to be
499 // processed starting from the leaves, otherwise rustdoc will not
500 // create correct links between crates because rustdoc depends on the
501 // existence of the output directories to know if it should be a local
503 let krates = ["core", "alloc", "std", "proc_macro", "test"];
504 for krate in &krates {
505 run_cargo_rustdoc_for(krate);
506 if paths.iter().any(|p| p == krate) {
507 // No need to document more of the libraries if we have the one we want.
511 builder.cp_r(&out_dir, &out);
513 // Look for library/std, library/core etc in the `x.py doc` arguments and
514 // open the corresponding rendered docs.
515 for requested_crate in paths {
516 if krates.iter().any(|k| *k == requested_crate.as_str()) {
517 let index = out.join(requested_crate).join("index.html");
518 open(builder, &index);
524 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
527 pub target: TargetSelection,
530 impl Step for Rustc {
532 const DEFAULT: bool = true;
533 const ONLY_HOSTS: bool = true;
535 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
536 let builder = run.builder;
537 run.krate("rustc-main").path("compiler").default_condition(builder.config.compiler_docs)
540 fn make_run(run: RunConfig<'_>) {
541 run.builder.ensure(Rustc { stage: run.builder.top_stage, target: run.target });
544 /// Generates compiler documentation.
546 /// This will generate all documentation for compiler and dependencies.
547 /// Compiler documentation is distributed separately, so we make sure
548 /// we do not merge it with the other documentation from std, test and
549 /// proc_macros. This is largely just a wrapper around `cargo doc`.
550 fn run(self, builder: &Builder<'_>) {
551 let stage = self.stage;
552 let target = self.target;
558 let components = components_simplified(path);
559 components.len() >= 2 && components[0] == "compiler"
561 .collect::<Vec<_>>();
563 // This is the intended out directory for compiler documentation.
564 let out = builder.compiler_doc_out(target);
565 t!(fs::create_dir_all(&out));
567 // Build the standard library, so that proc-macros can use it.
568 // (Normally, only the metadata would be necessary, but proc-macros are special since they run at compile-time.)
569 let compiler = builder.compiler(stage, builder.config.build);
570 builder.ensure(compile::Std { compiler, target: builder.config.build });
572 builder.info(&format!("Documenting stage{} compiler ({})", stage, target));
574 // This uses a shared directory so that librustdoc documentation gets
575 // correctly built and merged with the rustc documentation. This is
576 // needed because rustdoc is built in a different directory from
577 // rustc. rustdoc needs to be able to see everything, for example when
578 // merging the search index, or generating local (relative) links.
579 let out_dir = builder.stage_out(compiler, Mode::Rustc).join(target.triple).join("doc");
580 t!(symlink_dir_force(&builder.config, &out, &out_dir));
581 // Cargo puts proc macros in `target/doc` even if you pass `--target`
582 // explicitly (https://github.com/rust-lang/cargo/issues/7677).
583 let proc_macro_out_dir = builder.stage_out(compiler, Mode::Rustc).join("doc");
584 t!(symlink_dir_force(&builder.config, &out, &proc_macro_out_dir));
586 // Build cargo command.
587 let mut cargo = builder.cargo(compiler, Mode::Rustc, SourceType::InTree, target, "doc");
588 cargo.rustdocflag("--document-private-items");
589 // Since we always pass --document-private-items, there's no need to warn about linking to private items.
590 cargo.rustdocflag("-Arustdoc::private-intra-doc-links");
591 cargo.rustdocflag("--enable-index-page");
592 cargo.rustdocflag("-Zunstable-options");
593 cargo.rustdocflag("-Znormalize-docs");
594 cargo.rustdocflag("--show-type-layout");
595 cargo.rustdocflag("--generate-link-to-definition");
596 compile::rustc_cargo(builder, &mut cargo, target);
597 cargo.arg("-Zunstable-options");
598 cargo.arg("-Zskip-rustdoc-fingerprint");
600 // Only include compiler crates, no dependencies of those, such as `libc`.
601 // Do link to dependencies on `docs.rs` however using `rustdoc-map`.
602 cargo.arg("--no-deps");
603 cargo.arg("-Zrustdoc-map");
605 // FIXME: `-Zrustdoc-map` does not yet correctly work for transitive dependencies,
606 // once this is no longer an issue the special case for `ena` can be removed.
607 cargo.rustdocflag("--extern-html-root-url");
608 cargo.rustdocflag("ena=https://docs.rs/ena/latest/");
610 let root_crates = if paths.is_empty() {
612 INTERNER.intern_str("rustc_driver"),
613 INTERNER.intern_str("rustc_codegen_llvm"),
614 INTERNER.intern_str("rustc_codegen_ssa"),
617 paths.into_iter().map(|p| builder.crate_paths[p]).collect()
619 // Find dependencies for top level crates.
620 let compiler_crates = root_crates.iter().flat_map(|krate| {
621 builder.in_tree_crates(krate, Some(target)).into_iter().map(|krate| krate.name)
624 let mut to_open = None;
625 for krate in compiler_crates {
626 // Create all crate output directories first to make sure rustdoc uses
628 // FIXME: Cargo should probably do this itself.
629 t!(fs::create_dir_all(out_dir.join(krate)));
630 cargo.arg("-p").arg(krate);
631 if to_open.is_none() {
632 to_open = Some(krate);
636 builder.run(&mut cargo.into());
637 // Let's open the first crate documentation page:
638 if let Some(krate) = to_open {
639 let index = out.join(krate).join("index.html");
640 open(builder, &index);
645 macro_rules! tool_doc {
646 ($tool: ident, $should_run: literal, $path: literal, [$($krate: literal),+ $(,)?] $(,)?) => {
647 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
649 target: TargetSelection,
652 impl Step for $tool {
654 const DEFAULT: bool = true;
655 const ONLY_HOSTS: bool = true;
657 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
658 let builder = run.builder;
659 run.krate($should_run).default_condition(builder.config.compiler_docs)
662 fn make_run(run: RunConfig<'_>) {
663 run.builder.ensure($tool { target: run.target });
666 /// Generates compiler documentation.
668 /// This will generate all documentation for compiler and dependencies.
669 /// Compiler documentation is distributed separately, so we make sure
670 /// we do not merge it with the other documentation from std, test and
671 /// proc_macros. This is largely just a wrapper around `cargo doc`.
672 fn run(self, builder: &Builder<'_>) {
673 let stage = builder.top_stage;
674 let target = self.target;
676 // This is the intended out directory for compiler documentation.
677 let out = builder.compiler_doc_out(target);
678 t!(fs::create_dir_all(&out));
680 // Build rustc docs so that we generate relative links.
681 builder.ensure(Rustc { stage, target });
682 // Rustdoc needs the rustc sysroot available to build.
683 // FIXME: is there a way to only ensure `check::Rustc` here? Last time I tried it failed
684 // with strange errors, but only on a full bors test ...
685 let compiler = builder.compiler(stage, builder.config.build);
686 builder.ensure(compile::Rustc { compiler, target });
690 "Documenting stage{} {} ({})",
692 stringify!($tool).to_lowercase(),
697 // Symlink compiler docs to the output directory of rustdoc documentation.
698 let out_dir = builder.stage_out(compiler, Mode::ToolRustc).join(target.triple).join("doc");
699 t!(fs::create_dir_all(&out_dir));
700 t!(symlink_dir_force(&builder.config, &out, &out_dir));
702 // Build cargo command.
703 let mut cargo = prepare_tool_cargo(
714 cargo.arg("-Zskip-rustdoc-fingerprint");
715 // Only include compiler crates, no dependencies of those, such as `libc`.
716 cargo.arg("--no-deps");
718 cargo.arg("-p").arg($krate);
721 cargo.rustdocflag("--document-private-items");
722 cargo.rustdocflag("--enable-index-page");
723 cargo.rustdocflag("--show-type-layout");
724 cargo.rustdocflag("--generate-link-to-definition");
725 cargo.rustdocflag("-Zunstable-options");
726 builder.run(&mut cargo.into());
732 tool_doc!(Rustdoc, "rustdoc-tool", "src/tools/rustdoc", ["rustdoc", "rustdoc-json-types"]);
737 ["rustfmt-nightly", "rustfmt-config_proc_macro"],
739 tool_doc!(Clippy, "clippy", "src/tools/clippy", ["clippy_utils"]);
741 #[derive(Ord, PartialOrd, Debug, Copy, Clone, Hash, PartialEq, Eq)]
742 pub struct ErrorIndex {
743 pub target: TargetSelection,
746 impl Step for ErrorIndex {
748 const DEFAULT: bool = true;
749 const ONLY_HOSTS: bool = true;
751 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
752 let builder = run.builder;
753 run.path("src/tools/error_index_generator").default_condition(builder.config.docs)
756 fn make_run(run: RunConfig<'_>) {
757 let target = run.target;
758 run.builder.ensure(ErrorIndex { target });
761 /// Generates the HTML rendered error-index by running the
762 /// `error_index_generator` tool.
763 fn run(self, builder: &Builder<'_>) {
764 builder.info(&format!("Documenting error index ({})", self.target));
765 let out = builder.doc_out(self.target);
766 t!(fs::create_dir_all(&out));
767 let mut index = tool::ErrorIndex::command(builder);
769 index.arg(out.join("error-index.html"));
770 index.arg(&builder.version);
772 builder.run(&mut index);
776 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
777 pub struct UnstableBookGen {
778 target: TargetSelection,
781 impl Step for UnstableBookGen {
783 const DEFAULT: bool = true;
784 const ONLY_HOSTS: bool = true;
786 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
787 let builder = run.builder;
788 run.path("src/tools/unstable-book-gen").default_condition(builder.config.docs)
791 fn make_run(run: RunConfig<'_>) {
792 run.builder.ensure(UnstableBookGen { target: run.target });
795 fn run(self, builder: &Builder<'_>) {
796 let target = self.target;
798 builder.info(&format!("Generating unstable book md files ({})", target));
799 let out = builder.md_doc_out(target).join("unstable-book");
800 builder.create_dir(&out);
801 builder.remove_dir(&out);
802 let mut cmd = builder.tool_cmd(Tool::UnstableBookGen);
803 cmd.arg(builder.src.join("library"));
804 cmd.arg(builder.src.join("compiler"));
805 cmd.arg(builder.src.join("src"));
808 builder.run(&mut cmd);
812 fn symlink_dir_force(config: &Config, src: &Path, dst: &Path) -> io::Result<()> {
816 if let Ok(m) = fs::symlink_metadata(dst) {
817 if m.file_type().is_dir() {
818 fs::remove_dir_all(dst)?;
820 // handle directory junctions on windows by falling back to
822 fs::remove_file(dst).or_else(|_| fs::remove_dir(dst))?;
826 symlink_dir(config, src, dst)
829 #[derive(Ord, PartialOrd, Debug, Copy, Clone, Hash, PartialEq, Eq)]
830 pub struct RustcBook {
831 pub compiler: Compiler,
832 pub target: TargetSelection,
836 impl Step for RustcBook {
838 const DEFAULT: bool = true;
839 const ONLY_HOSTS: bool = true;
841 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
842 let builder = run.builder;
843 run.path("src/doc/rustc").default_condition(builder.config.docs)
846 fn make_run(run: RunConfig<'_>) {
847 run.builder.ensure(RustcBook {
848 compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
854 /// Builds the rustc book.
856 /// The lints are auto-generated by a tool, and then merged into the book
857 /// in the "md-doc" directory in the build output directory. Then
858 /// "rustbook" is used to convert it to HTML.
859 fn run(self, builder: &Builder<'_>) {
860 let out_base = builder.md_doc_out(self.target).join("rustc");
861 t!(fs::create_dir_all(&out_base));
862 let out_listing = out_base.join("src/lints");
863 builder.cp_r(&builder.src.join("src/doc/rustc"), &out_base);
864 builder.info(&format!("Generating lint docs ({})", self.target));
866 let rustc = builder.rustc(self.compiler);
867 // The tool runs `rustc` for extracting output examples, so it needs a
868 // functional sysroot.
869 builder.ensure(compile::Std { compiler: self.compiler, target: self.target });
870 let mut cmd = builder.tool_cmd(Tool::LintDocs);
872 cmd.arg(builder.src.join("compiler"));
874 cmd.arg(&out_listing);
877 cmd.arg("--rustc-target").arg(&self.target.rustc_target_arg());
878 if builder.config.verbose() {
879 cmd.arg("--verbose");
882 cmd.arg("--validate");
884 if !builder.unstable_features() {
885 // We need to validate nightly features, even on the stable channel.
886 cmd.env("RUSTC_BOOTSTRAP", "1");
888 // If the lib directories are in an unusual location (changed in
889 // config.toml), then this needs to explicitly update the dylib search
891 builder.add_rustc_lib_path(self.compiler, &mut cmd);
892 builder.run(&mut cmd);
893 // Run rustbook/mdbook to generate the HTML pages.
894 builder.ensure(RustbookSrc {
896 name: INTERNER.intern_str("rustc"),
897 src: INTERNER.intern_path(out_base),
899 if builder.was_invoked_explicitly::<Self>(Kind::Doc) {
900 let out = builder.doc_out(self.target);
901 let index = out.join("rustc").join("index.html");
902 open(builder, &index);