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
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 ClippyBook, "src/tools/clippy/book", "clippy";
79 EditionGuide, "src/doc/edition-guide", "edition-guide", submodule;
80 EmbeddedBook, "src/doc/embedded-book", "embedded-book", submodule;
81 Nomicon, "src/doc/nomicon", "nomicon", submodule;
82 Reference, "src/doc/reference", "reference", submodule;
83 RustByExample, "src/doc/rust-by-example", "rust-by-example", submodule;
84 RustdocBook, "src/doc/rustdoc", "rustdoc";
85 StyleGuide, "src/doc/style-guide", "style-guide";
88 // "library/std" -> ["library", "std"]
90 // Used for deciding whether a particular step is one requested by the user on
91 // the `x.py doc` command line, which determines whether `--open` will open that
93 pub(crate) fn components_simplified(path: &PathBuf) -> Vec<&str> {
94 path.iter().map(|component| component.to_str().unwrap_or("???")).collect()
97 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
98 pub struct UnstableBook {
99 target: TargetSelection,
102 impl Step for UnstableBook {
104 const DEFAULT: bool = true;
106 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
107 let builder = run.builder;
108 run.path("src/doc/unstable-book").default_condition(builder.config.docs)
111 fn make_run(run: RunConfig<'_>) {
112 run.builder.ensure(UnstableBook { target: run.target });
115 fn run(self, builder: &Builder<'_>) {
116 builder.ensure(UnstableBookGen { target: self.target });
117 builder.ensure(RustbookSrc {
119 name: INTERNER.intern_str("unstable-book"),
120 src: INTERNER.intern_path(builder.md_doc_out(self.target).join("unstable-book")),
125 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
127 target: TargetSelection,
128 name: Interned<String>,
129 src: Interned<PathBuf>,
132 impl Step for RustbookSrc {
135 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
139 /// Invoke `rustbook` for `target` for the doc book `name` from the `src` path.
141 /// This will not actually generate any documentation if the documentation has
142 /// already been generated.
143 fn run(self, builder: &Builder<'_>) {
144 let target = self.target;
145 let name = self.name;
147 let out = builder.doc_out(target);
148 t!(fs::create_dir_all(&out));
150 let out = out.join(name);
151 let index = out.join("index.html");
152 let rustbook = builder.tool_exe(Tool::Rustbook);
153 let mut rustbook_cmd = builder.tool_cmd(Tool::Rustbook);
154 if builder.config.dry_run() || up_to_date(&src, &index) && up_to_date(&rustbook, &index) {
157 builder.info(&format!("Rustbook ({}) - {}", target, name));
158 let _ = fs::remove_dir_all(&out);
160 builder.run(rustbook_cmd.arg("build").arg(&src).arg("-d").arg(out));
164 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
167 target: TargetSelection,
170 impl Step for TheBook {
172 const DEFAULT: bool = true;
174 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
175 let builder = run.builder;
176 run.path("src/doc/book").default_condition(builder.config.docs)
179 fn make_run(run: RunConfig<'_>) {
180 run.builder.ensure(TheBook {
181 compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
186 /// Builds the book and associated stuff.
188 /// We need to build:
191 /// * Older edition redirects
192 /// * Version info and CSS
195 fn run(self, builder: &Builder<'_>) {
196 let relative_path = Path::new("src").join("doc").join("book");
197 builder.update_submodule(&relative_path);
199 let compiler = self.compiler;
200 let target = self.target;
203 builder.ensure(RustbookSrc {
205 name: INTERNER.intern_str("book"),
206 src: INTERNER.intern_path(builder.src.join(&relative_path)),
209 // building older edition redirects
210 for edition in &["first-edition", "second-edition", "2018-edition"] {
211 builder.ensure(RustbookSrc {
213 name: INTERNER.intern_string(format!("book/{}", edition)),
214 src: INTERNER.intern_path(builder.src.join(&relative_path).join(edition)),
218 // build the version info page and CSS
219 let shared_assets = builder.ensure(SharedAssets { target });
221 // build the redirect pages
222 builder.info(&format!("Documenting book redirect pages ({})", target));
223 for file in t!(fs::read_dir(builder.src.join(&relative_path).join("redirects"))) {
225 let path = file.path();
226 let path = path.to_str().unwrap();
228 invoke_rustdoc(builder, compiler, &shared_assets, target, path);
231 let out = builder.doc_out(target);
232 let index = out.join("book").join("index.html");
233 builder.maybe_open_in_browser::<Self>(index);
238 builder: &Builder<'_>,
240 shared_assets: &SharedAssetsPaths,
241 target: TargetSelection,
244 let out = builder.doc_out(target);
246 let path = builder.src.join("src/doc").join(markdown);
248 let header = builder.src.join("src/doc/redirect.inc");
249 let footer = builder.src.join("src/doc/footer.inc");
251 let mut cmd = builder.rustdoc_cmd(compiler);
253 let out = out.join("book");
255 cmd.arg("--html-after-content")
257 .arg("--html-before-content")
258 .arg(&shared_assets.version_info)
259 .arg("--html-in-header")
261 .arg("--markdown-no-toc")
262 .arg("--markdown-playground-url")
263 .arg("https://play.rust-lang.org/")
267 .arg("--markdown-css")
270 if !builder.config.docs_minification {
271 cmd.arg("-Z").arg("unstable-options").arg("--disable-minification");
274 builder.run(&mut cmd);
277 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
278 pub struct Standalone {
280 target: TargetSelection,
283 impl Step for Standalone {
285 const DEFAULT: bool = true;
287 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
288 let builder = run.builder;
289 run.path("src/doc").alias("standalone").default_condition(builder.config.docs)
292 fn make_run(run: RunConfig<'_>) {
293 run.builder.ensure(Standalone {
294 compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
299 /// Generates all standalone documentation as compiled by the rustdoc in `stage`
300 /// for the `target` into `out`.
302 /// This will list all of `src/doc` looking for markdown files and appropriately
303 /// perform transformations like substituting `VERSION`, `SHORT_HASH`, and
304 /// `STAMP` along with providing the various header/footer HTML we've customized.
306 /// In the end, this is just a glorified wrapper around rustdoc!
307 fn run(self, builder: &Builder<'_>) {
308 let target = self.target;
309 let compiler = self.compiler;
310 builder.info(&format!("Documenting standalone ({})", target));
311 let out = builder.doc_out(target);
312 t!(fs::create_dir_all(&out));
314 let version_info = builder.ensure(SharedAssets { target: self.target }).version_info;
316 let favicon = builder.src.join("src/doc/favicon.inc");
317 let footer = builder.src.join("src/doc/footer.inc");
318 let full_toc = builder.src.join("src/doc/full-toc.inc");
320 for file in t!(fs::read_dir(builder.src.join("src/doc"))) {
322 let path = file.path();
323 let filename = path.file_name().unwrap().to_str().unwrap();
324 if !filename.ends_with(".md") || filename == "README.md" {
328 let html = out.join(filename).with_extension("html");
329 let rustdoc = builder.rustdoc(compiler);
330 if up_to_date(&path, &html)
331 && up_to_date(&footer, &html)
332 && up_to_date(&favicon, &html)
333 && up_to_date(&full_toc, &html)
334 && (builder.config.dry_run() || up_to_date(&version_info, &html))
335 && (builder.config.dry_run() || up_to_date(&rustdoc, &html))
340 let mut cmd = builder.rustdoc_cmd(compiler);
341 // Needed for --index-page flag
342 cmd.arg("-Z").arg("unstable-options");
344 cmd.arg("--html-after-content")
346 .arg("--html-before-content")
348 .arg("--html-in-header")
350 .arg("--markdown-no-toc")
352 .arg(&builder.src.join("src/doc/index.md"))
353 .arg("--markdown-playground-url")
354 .arg("https://play.rust-lang.org/")
359 if !builder.config.docs_minification {
360 cmd.arg("--disable-minification");
363 if filename == "not_found.md" {
364 cmd.arg("--markdown-css").arg("https://doc.rust-lang.org/rust.css");
366 cmd.arg("--markdown-css").arg("rust.css");
368 builder.run(&mut cmd);
371 // We open doc/index.html as the default if invoked as `x.py doc --open`
372 // with no particular explicit doc requested (e.g. library/core).
373 if builder.paths.is_empty() || builder.was_invoked_explicitly::<Self>(Kind::Doc) {
374 let index = out.join("index.html");
375 builder.open_in_browser(&index);
380 #[derive(Debug, Clone)]
381 pub struct SharedAssetsPaths {
382 pub version_info: PathBuf,
385 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
386 pub struct SharedAssets {
387 target: TargetSelection,
390 impl Step for SharedAssets {
391 type Output = SharedAssetsPaths;
392 const DEFAULT: bool = false;
394 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
395 // Other tasks depend on this, no need to execute it on its own
399 // Generate shared resources used by other pieces of documentation.
400 fn run(self, builder: &Builder<'_>) -> Self::Output {
401 let out = builder.doc_out(self.target);
403 let version_input = builder.src.join("src").join("doc").join("version_info.html.template");
404 let version_info = out.join("version_info.html");
405 if !builder.config.dry_run() && !up_to_date(&version_input, &version_info) {
406 let info = t!(fs::read_to_string(&version_input))
407 .replace("VERSION", &builder.rust_release())
408 .replace("SHORT_HASH", builder.rust_info.sha_short().unwrap_or(""))
409 .replace("STAMP", builder.rust_info.sha().unwrap_or(""));
410 t!(fs::write(&version_info, &info));
413 builder.copy(&builder.src.join("src").join("doc").join("rust.css"), &out.join("rust.css"));
415 SharedAssetsPaths { version_info }
419 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
422 pub target: TargetSelection,
423 pub format: DocumentationFormat,
428 const DEFAULT: bool = true;
430 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
431 let builder = run.builder;
432 run.all_krates("test").path("library").default_condition(builder.config.docs)
435 fn make_run(run: RunConfig<'_>) {
436 run.builder.ensure(Std {
437 stage: run.builder.top_stage,
439 format: if run.builder.config.cmd.json() {
440 DocumentationFormat::JSON
442 DocumentationFormat::HTML
447 /// Compile all standard library documentation.
449 /// This will generate all documentation for the standard library and its
450 /// dependencies. This is largely just a wrapper around `cargo doc`.
451 fn run(self, builder: &Builder<'_>) {
452 let stage = self.stage;
453 let target = self.target;
454 let out = match self.format {
455 DocumentationFormat::HTML => builder.doc_out(target),
456 DocumentationFormat::JSON => builder.json_doc_out(target),
459 t!(fs::create_dir_all(&out));
461 builder.ensure(SharedAssets { target: self.target });
463 let index_page = builder.src.join("src/doc/index.md").into_os_string();
464 let mut extra_args = match self.format {
465 DocumentationFormat::HTML => vec![
466 OsStr::new("--markdown-css"),
467 OsStr::new("rust.css"),
468 OsStr::new("--markdown-no-toc"),
469 OsStr::new("--index-page"),
472 DocumentationFormat::JSON => vec![OsStr::new("--output-format"), OsStr::new("json")],
475 if !builder.config.docs_minification {
476 extra_args.push(OsStr::new("--disable-minification"));
479 let requested_crates = builder
482 .map(components_simplified)
484 if path.len() >= 2 && path.get(0) == Some(&"library") {
486 Some(path[1].to_owned())
487 } else if !path.is_empty() {
489 Some(path[0].to_owned())
491 // all library crates
495 .collect::<Vec<_>>();
497 doc_std(builder, self.format, stage, target, &out, &extra_args, &requested_crates);
499 // Don't open if the format is json
500 if let DocumentationFormat::JSON = self.format {
504 // Look for library/std, library/core etc in the `x.py doc` arguments and
505 // open the corresponding rendered docs.
506 for requested_crate in requested_crates {
507 if STD_PUBLIC_CRATES.iter().any(|k| *k == requested_crate.as_str()) {
508 let index = out.join(requested_crate).join("index.html");
509 builder.open_in_browser(index);
515 /// Name of the crates that are visible to consumers of the standard library.
516 /// Documentation for internal crates is handled by the rustc step, so internal crates will show
519 /// Order here is important!
520 /// Crates need to be processed starting from the leaves, otherwise rustdoc will not
521 /// create correct links between crates because rustdoc depends on the
522 /// existence of the output directories to know if it should be a local
524 const STD_PUBLIC_CRATES: [&str; 5] = ["core", "alloc", "std", "proc_macro", "test"];
526 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
527 pub enum DocumentationFormat {
532 impl DocumentationFormat {
533 fn as_str(&self) -> &str {
535 DocumentationFormat::HTML => "HTML",
536 DocumentationFormat::JSON => "JSON",
541 /// Build the documentation for public standard library crates.
543 /// `requested_crates` can be used to build only a subset of the crates. If empty, all crates will
546 builder: &Builder<'_>,
547 format: DocumentationFormat,
549 target: TargetSelection,
551 extra_args: &[&OsStr],
552 requested_crates: &[String],
554 builder.info(&format!(
555 "Documenting stage{} std ({}) in {} format",
560 if builder.no_std(target) == Some(true) {
562 "building std documentation for no_std target {target} is not supported\n\
563 Set `docs = false` in the config to disable documentation."
566 let compiler = builder.compiler(stage, builder.config.build);
567 // This is directory where the compiler will place the output of the command.
568 // We will then copy the files from this directory into the final `out` directory, the specified
569 // as a function parameter.
570 let out_dir = builder.stage_out(compiler, Mode::Std).join(target.triple).join("doc");
571 // `cargo` uses the same directory for both JSON docs and HTML docs.
572 // This could lead to cross-contamination when copying files into the specified `out` directory.
578 // could lead to HTML docs being copied into the JSON docs output directory.
579 // To avoid this issue, we clean the doc folder before invoking `cargo`.
580 if out_dir.exists() {
581 builder.remove_dir(&out_dir);
584 let run_cargo_rustdoc_for = |package: &str| {
585 let mut cargo = builder.cargo(compiler, Mode::Std, SourceType::InTree, target, "rustdoc");
586 compile::std_cargo(builder, target, compiler.stage, &mut cargo);
590 .arg("-Zskip-rustdoc-fingerprint")
593 .arg("unstable-options")
594 .arg("--resource-suffix")
595 .arg(&builder.version)
597 builder.run(&mut cargo.into());
600 for krate in STD_PUBLIC_CRATES {
601 run_cargo_rustdoc_for(krate);
602 if requested_crates.iter().any(|p| p == krate) {
603 // No need to document more of the libraries if we have the one we want.
608 builder.cp_r(&out_dir, &out);
611 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
614 pub target: TargetSelection,
617 impl Step for Rustc {
619 const DEFAULT: bool = true;
620 const ONLY_HOSTS: bool = true;
622 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
623 let builder = run.builder;
624 run.crate_or_deps("rustc-main")
626 .default_condition(builder.config.compiler_docs)
629 fn make_run(run: RunConfig<'_>) {
630 run.builder.ensure(Rustc { stage: run.builder.top_stage, target: run.target });
633 /// Generates compiler documentation.
635 /// This will generate all documentation for compiler and dependencies.
636 /// Compiler documentation is distributed separately, so we make sure
637 /// we do not merge it with the other documentation from std, test and
638 /// proc_macros. This is largely just a wrapper around `cargo doc`.
639 fn run(self, builder: &Builder<'_>) {
640 let stage = self.stage;
641 let target = self.target;
647 let components = components_simplified(path);
648 components.len() >= 2 && components[0] == "compiler"
650 .collect::<Vec<_>>();
652 // This is the intended out directory for compiler documentation.
653 let out = builder.compiler_doc_out(target);
654 t!(fs::create_dir_all(&out));
656 // Build the standard library, so that proc-macros can use it.
657 // (Normally, only the metadata would be necessary, but proc-macros are special since they run at compile-time.)
658 let compiler = builder.compiler(stage, builder.config.build);
659 builder.ensure(compile::Std::new(compiler, builder.config.build));
661 builder.info(&format!("Documenting stage{} compiler ({})", stage, target));
663 // This uses a shared directory so that librustdoc documentation gets
664 // correctly built and merged with the rustc documentation. This is
665 // needed because rustdoc is built in a different directory from
666 // rustc. rustdoc needs to be able to see everything, for example when
667 // merging the search index, or generating local (relative) links.
668 let out_dir = builder.stage_out(compiler, Mode::Rustc).join(target.triple).join("doc");
669 t!(symlink_dir_force(&builder.config, &out, &out_dir));
670 // Cargo puts proc macros in `target/doc` even if you pass `--target`
671 // explicitly (https://github.com/rust-lang/cargo/issues/7677).
672 let proc_macro_out_dir = builder.stage_out(compiler, Mode::Rustc).join("doc");
673 t!(symlink_dir_force(&builder.config, &out, &proc_macro_out_dir));
675 // Build cargo command.
676 let mut cargo = builder.cargo(compiler, Mode::Rustc, SourceType::InTree, target, "doc");
677 cargo.rustdocflag("--document-private-items");
678 // Since we always pass --document-private-items, there's no need to warn about linking to private items.
679 cargo.rustdocflag("-Arustdoc::private-intra-doc-links");
680 cargo.rustdocflag("--enable-index-page");
681 cargo.rustdocflag("-Zunstable-options");
682 cargo.rustdocflag("-Znormalize-docs");
683 cargo.rustdocflag("--show-type-layout");
684 cargo.rustdocflag("--generate-link-to-definition");
685 compile::rustc_cargo(builder, &mut cargo, target);
686 cargo.arg("-Zunstable-options");
687 cargo.arg("-Zskip-rustdoc-fingerprint");
689 // Only include compiler crates, no dependencies of those, such as `libc`.
690 // Do link to dependencies on `docs.rs` however using `rustdoc-map`.
691 cargo.arg("--no-deps");
692 cargo.arg("-Zrustdoc-map");
694 // FIXME: `-Zrustdoc-map` does not yet correctly work for transitive dependencies,
695 // once this is no longer an issue the special case for `ena` can be removed.
696 cargo.rustdocflag("--extern-html-root-url");
697 cargo.rustdocflag("ena=https://docs.rs/ena/latest/");
699 let root_crates = if paths.is_empty() {
701 INTERNER.intern_str("rustc_driver"),
702 INTERNER.intern_str("rustc_codegen_llvm"),
703 INTERNER.intern_str("rustc_codegen_ssa"),
706 paths.into_iter().map(|p| builder.crate_paths[p]).collect()
708 // Find dependencies for top level crates.
709 let compiler_crates = root_crates.iter().flat_map(|krate| {
710 builder.in_tree_crates(krate, Some(target)).into_iter().map(|krate| krate.name)
713 let mut to_open = None;
714 for krate in compiler_crates {
715 // Create all crate output directories first to make sure rustdoc uses
717 // FIXME: Cargo should probably do this itself.
718 t!(fs::create_dir_all(out_dir.join(krate)));
719 cargo.arg("-p").arg(krate);
720 if to_open.is_none() {
721 to_open = Some(krate);
725 builder.run(&mut cargo.into());
726 // Let's open the first crate documentation page:
727 if let Some(krate) = to_open {
728 let index = out.join(krate).join("index.html");
729 builder.open_in_browser(index);
734 macro_rules! tool_doc {
735 ($tool: ident, $should_run: literal, $path: literal, [$($krate: literal),+ $(,)?] $(,)?) => {
736 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
738 target: TargetSelection,
741 impl Step for $tool {
743 const DEFAULT: bool = true;
744 const ONLY_HOSTS: bool = true;
746 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
747 let builder = run.builder;
748 run.crate_or_deps($should_run).default_condition(builder.config.compiler_docs)
751 fn make_run(run: RunConfig<'_>) {
752 run.builder.ensure($tool { target: run.target });
755 /// Generates compiler documentation.
757 /// This will generate all documentation for compiler and dependencies.
758 /// Compiler documentation is distributed separately, so we make sure
759 /// we do not merge it with the other documentation from std, test and
760 /// proc_macros. This is largely just a wrapper around `cargo doc`.
761 fn run(self, builder: &Builder<'_>) {
762 let stage = builder.top_stage;
763 let target = self.target;
765 // This is the intended out directory for compiler documentation.
766 let out = builder.compiler_doc_out(target);
767 t!(fs::create_dir_all(&out));
769 // Build rustc docs so that we generate relative links.
770 builder.ensure(Rustc { stage, target });
771 // Rustdoc needs the rustc sysroot available to build.
772 // FIXME: is there a way to only ensure `check::Rustc` here? Last time I tried it failed
773 // with strange errors, but only on a full bors test ...
774 let compiler = builder.compiler(stage, builder.config.build);
775 builder.ensure(compile::Rustc::new(compiler, target));
779 "Documenting stage{} {} ({})",
781 stringify!($tool).to_lowercase(),
786 // Symlink compiler docs to the output directory of rustdoc documentation.
787 let out_dir = builder.stage_out(compiler, Mode::ToolRustc).join(target.triple).join("doc");
788 t!(fs::create_dir_all(&out_dir));
789 t!(symlink_dir_force(&builder.config, &out, &out_dir));
791 // Build cargo command.
792 let mut cargo = prepare_tool_cargo(
803 cargo.arg("-Zskip-rustdoc-fingerprint");
804 // Only include compiler crates, no dependencies of those, such as `libc`.
805 cargo.arg("--no-deps");
807 cargo.arg("-p").arg($krate);
810 cargo.rustdocflag("--document-private-items");
811 cargo.rustdocflag("--enable-index-page");
812 cargo.rustdocflag("--show-type-layout");
813 cargo.rustdocflag("--generate-link-to-definition");
814 cargo.rustdocflag("-Zunstable-options");
815 builder.run(&mut cargo.into());
821 tool_doc!(Rustdoc, "rustdoc-tool", "src/tools/rustdoc", ["rustdoc", "rustdoc-json-types"],);
826 ["rustfmt-nightly", "rustfmt-config_proc_macro"],
828 tool_doc!(Clippy, "clippy", "src/tools/clippy", ["clippy_utils"]);
829 tool_doc!(Miri, "miri", "src/tools/miri", ["miri"]);
831 #[derive(Ord, PartialOrd, Debug, Copy, Clone, Hash, PartialEq, Eq)]
832 pub struct ErrorIndex {
833 pub target: TargetSelection,
836 impl Step for ErrorIndex {
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/tools/error_index_generator").default_condition(builder.config.docs)
846 fn make_run(run: RunConfig<'_>) {
847 let target = run.target;
848 run.builder.ensure(ErrorIndex { target });
851 /// Generates the HTML rendered error-index by running the
852 /// `error_index_generator` tool.
853 fn run(self, builder: &Builder<'_>) {
854 builder.info(&format!("Documenting error index ({})", self.target));
855 let out = builder.doc_out(self.target);
856 t!(fs::create_dir_all(&out));
857 let mut index = tool::ErrorIndex::command(builder);
860 index.arg(&builder.version);
862 builder.run(&mut index);
866 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
867 pub struct UnstableBookGen {
868 target: TargetSelection,
871 impl Step for UnstableBookGen {
873 const DEFAULT: bool = true;
874 const ONLY_HOSTS: bool = true;
876 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
877 let builder = run.builder;
878 run.path("src/tools/unstable-book-gen").default_condition(builder.config.docs)
881 fn make_run(run: RunConfig<'_>) {
882 run.builder.ensure(UnstableBookGen { target: run.target });
885 fn run(self, builder: &Builder<'_>) {
886 let target = self.target;
888 builder.info(&format!("Generating unstable book md files ({})", target));
889 let out = builder.md_doc_out(target).join("unstable-book");
890 builder.create_dir(&out);
891 builder.remove_dir(&out);
892 let mut cmd = builder.tool_cmd(Tool::UnstableBookGen);
893 cmd.arg(builder.src.join("library"));
894 cmd.arg(builder.src.join("compiler"));
895 cmd.arg(builder.src.join("src"));
898 builder.run(&mut cmd);
902 fn symlink_dir_force(config: &Config, src: &Path, dst: &Path) -> io::Result<()> {
903 if config.dry_run() {
906 if let Ok(m) = fs::symlink_metadata(dst) {
907 if m.file_type().is_dir() {
908 fs::remove_dir_all(dst)?;
910 // handle directory junctions on windows by falling back to
912 fs::remove_file(dst).or_else(|_| fs::remove_dir(dst))?;
916 symlink_dir(config, src, dst)
919 #[derive(Ord, PartialOrd, Debug, Copy, Clone, Hash, PartialEq, Eq)]
920 pub struct RustcBook {
921 pub compiler: Compiler,
922 pub target: TargetSelection,
926 impl Step for RustcBook {
928 const DEFAULT: bool = true;
929 const ONLY_HOSTS: bool = true;
931 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
932 let builder = run.builder;
933 run.path("src/doc/rustc").default_condition(builder.config.docs)
936 fn make_run(run: RunConfig<'_>) {
937 run.builder.ensure(RustcBook {
938 compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
944 /// Builds the rustc book.
946 /// The lints are auto-generated by a tool, and then merged into the book
947 /// in the "md-doc" directory in the build output directory. Then
948 /// "rustbook" is used to convert it to HTML.
949 fn run(self, builder: &Builder<'_>) {
950 let out_base = builder.md_doc_out(self.target).join("rustc");
951 t!(fs::create_dir_all(&out_base));
952 let out_listing = out_base.join("src/lints");
953 builder.cp_r(&builder.src.join("src/doc/rustc"), &out_base);
954 builder.info(&format!("Generating lint docs ({})", self.target));
956 let rustc = builder.rustc(self.compiler);
957 // The tool runs `rustc` for extracting output examples, so it needs a
958 // functional sysroot.
959 builder.ensure(compile::Std::new(self.compiler, self.target));
960 let mut cmd = builder.tool_cmd(Tool::LintDocs);
962 cmd.arg(builder.src.join("compiler"));
964 cmd.arg(&out_listing);
967 cmd.arg("--rustc-target").arg(&self.target.rustc_target_arg());
968 if builder.config.verbose() {
969 cmd.arg("--verbose");
972 cmd.arg("--validate");
974 if !builder.unstable_features() {
975 // We need to validate nightly features, even on the stable channel.
976 cmd.env("RUSTC_BOOTSTRAP", "1");
978 // If the lib directories are in an unusual location (changed in
979 // config.toml), then this needs to explicitly update the dylib search
981 builder.add_rustc_lib_path(self.compiler, &mut cmd);
982 builder.run(&mut cmd);
983 // Run rustbook/mdbook to generate the HTML pages.
984 builder.ensure(RustbookSrc {
986 name: INTERNER.intern_str("rustc"),
987 src: INTERNER.intern_path(out_base),
990 let out = builder.doc_out(self.target);
991 let index = out.join("rustc").join("index.html");
992 builder.maybe_open_in_browser::<Self>(index);