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 ClippyBook
, "src/tools/clippy/book", "clippy";
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").path("library").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 if builder
.no_std(target
) == Some(true) {
437 "building std documentation for no_std target {target} is not supported\n\
438 Set `docs = false` in the config to disable documentation."
441 let out
= builder
.doc_out(target
);
442 t
!(fs
::create_dir_all(&out
));
443 let compiler
= builder
.compiler(stage
, builder
.config
.build
);
445 let out_dir
= builder
.stage_out(compiler
, Mode
::Std
).join(target
.triple
).join("doc");
447 t
!(fs
::copy(builder
.src
.join("src/doc/rust.css"), out
.join("rust.css")));
449 let run_cargo_rustdoc_for
= |package
: &str| {
451 builder
.cargo(compiler
, Mode
::Std
, SourceType
::InTree
, target
, "rustdoc");
452 compile
::std_cargo(builder
, target
, compiler
.stage
, &mut cargo
);
457 .arg("-Zskip-rustdoc-fingerprint")
459 .arg("--markdown-css")
461 .arg("--markdown-no-toc")
463 .arg("unstable-options")
464 .arg("--resource-suffix")
465 .arg(&builder
.version
)
467 .arg(&builder
.src
.join("src/doc/index.md"));
469 if !builder
.config
.docs_minification
{
470 cargo
.arg("--disable-minification");
473 builder
.run(&mut cargo
.into());
479 .map(components_simplified
)
481 if path
.len() >= 2 && path
.get(0) == Some(&"library") {
483 Some(path
[1].to_owned())
484 } else if !path
.is_empty() {
486 Some(path
[0].to_owned())
488 // all library crates
492 .collect
::<Vec
<_
>>();
494 // Only build the following crates. While we could just iterate over the
495 // folder structure, that would also build internal crates that we do
496 // not want to show in documentation. These crates will later be visited
497 // by the rustc step, so internal documentation will show them.
499 // Note that the order here is important! The crates need to be
500 // processed starting from the leaves, otherwise rustdoc will not
501 // create correct links between crates because rustdoc depends on the
502 // existence of the output directories to know if it should be a local
504 let krates
= ["core", "alloc", "std", "proc_macro", "test"];
505 for krate
in &krates
{
506 run_cargo_rustdoc_for(krate
);
507 if paths
.iter().any(|p
| p
== krate
) {
508 // No need to document more of the libraries if we have the one we want.
512 builder
.cp_r(&out_dir
, &out
);
514 // Look for library/std, library/core etc in the `x.py doc` arguments and
515 // open the corresponding rendered docs.
516 for requested_crate
in paths
{
517 if krates
.iter().any(|k
| *k
== requested_crate
.as_str()) {
518 let index
= out
.join(requested_crate
).join("index.html");
519 open(builder
, &index
);
525 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
528 pub target
: TargetSelection
,
531 impl Step
for Rustc
{
533 const DEFAULT
: bool
= true;
534 const ONLY_HOSTS
: bool
= true;
536 fn should_run(run
: ShouldRun
<'_
>) -> ShouldRun
<'_
> {
537 let builder
= run
.builder
;
538 run
.crate_or_deps("rustc-main")
540 .default_condition(builder
.config
.compiler_docs
)
543 fn make_run(run
: RunConfig
<'_
>) {
544 run
.builder
.ensure(Rustc { stage: run.builder.top_stage, target: run.target }
);
547 /// Generates compiler documentation.
549 /// This will generate all documentation for compiler and dependencies.
550 /// Compiler documentation is distributed separately, so we make sure
551 /// we do not merge it with the other documentation from std, test and
552 /// proc_macros. This is largely just a wrapper around `cargo doc`.
553 fn run(self, builder
: &Builder
<'_
>) {
554 let stage
= self.stage
;
555 let target
= self.target
;
561 let components
= components_simplified(path
);
562 components
.len() >= 2 && components
[0] == "compiler"
564 .collect
::<Vec
<_
>>();
566 // This is the intended out directory for compiler documentation.
567 let out
= builder
.compiler_doc_out(target
);
568 t
!(fs
::create_dir_all(&out
));
570 // Build the standard library, so that proc-macros can use it.
571 // (Normally, only the metadata would be necessary, but proc-macros are special since they run at compile-time.)
572 let compiler
= builder
.compiler(stage
, builder
.config
.build
);
573 builder
.ensure(compile
::Std
::new(compiler
, builder
.config
.build
));
575 builder
.info(&format
!("Documenting stage{} compiler ({})", stage
, target
));
577 // This uses a shared directory so that librustdoc documentation gets
578 // correctly built and merged with the rustc documentation. This is
579 // needed because rustdoc is built in a different directory from
580 // rustc. rustdoc needs to be able to see everything, for example when
581 // merging the search index, or generating local (relative) links.
582 let out_dir
= builder
.stage_out(compiler
, Mode
::Rustc
).join(target
.triple
).join("doc");
583 t
!(symlink_dir_force(&builder
.config
, &out
, &out_dir
));
584 // Cargo puts proc macros in `target/doc` even if you pass `--target`
585 // explicitly (https://github.com/rust-lang/cargo/issues/7677).
586 let proc_macro_out_dir
= builder
.stage_out(compiler
, Mode
::Rustc
).join("doc");
587 t
!(symlink_dir_force(&builder
.config
, &out
, &proc_macro_out_dir
));
589 // Build cargo command.
590 let mut cargo
= builder
.cargo(compiler
, Mode
::Rustc
, SourceType
::InTree
, target
, "doc");
591 cargo
.rustdocflag("--document-private-items");
592 // Since we always pass --document-private-items, there's no need to warn about linking to private items.
593 cargo
.rustdocflag("-Arustdoc::private-intra-doc-links");
594 cargo
.rustdocflag("--enable-index-page");
595 cargo
.rustdocflag("-Zunstable-options");
596 cargo
.rustdocflag("-Znormalize-docs");
597 cargo
.rustdocflag("--show-type-layout");
598 cargo
.rustdocflag("--generate-link-to-definition");
599 compile
::rustc_cargo(builder
, &mut cargo
, target
);
600 cargo
.arg("-Zunstable-options");
601 cargo
.arg("-Zskip-rustdoc-fingerprint");
603 // Only include compiler crates, no dependencies of those, such as `libc`.
604 // Do link to dependencies on `docs.rs` however using `rustdoc-map`.
605 cargo
.arg("--no-deps");
606 cargo
.arg("-Zrustdoc-map");
608 // FIXME: `-Zrustdoc-map` does not yet correctly work for transitive dependencies,
609 // once this is no longer an issue the special case for `ena` can be removed.
610 cargo
.rustdocflag("--extern-html-root-url");
611 cargo
.rustdocflag("ena=https://docs.rs/ena/latest/");
613 let root_crates
= if paths
.is_empty() {
615 INTERNER
.intern_str("rustc_driver"),
616 INTERNER
.intern_str("rustc_codegen_llvm"),
617 INTERNER
.intern_str("rustc_codegen_ssa"),
620 paths
.into_iter().map(|p
| builder
.crate_paths
[p
]).collect()
622 // Find dependencies for top level crates.
623 let compiler_crates
= root_crates
.iter().flat_map(|krate
| {
624 builder
.in_tree_crates(krate
, Some(target
)).into_iter().map(|krate
| krate
.name
)
627 let mut to_open
= None
;
628 for krate
in compiler_crates
{
629 // Create all crate output directories first to make sure rustdoc uses
631 // FIXME: Cargo should probably do this itself.
632 t
!(fs
::create_dir_all(out_dir
.join(krate
)));
633 cargo
.arg("-p").arg(krate
);
634 if to_open
.is_none() {
635 to_open
= Some(krate
);
639 builder
.run(&mut cargo
.into());
640 // Let's open the first crate documentation page:
641 if let Some(krate
) = to_open
{
642 let index
= out
.join(krate
).join("index.html");
643 open(builder
, &index
);
648 macro_rules
! tool_doc
{
649 ($tool
: ident
, $should_run
: literal
, $path
: literal
, [$
($krate
: literal
),+ $
(,)?
], in_tree
= $in_tree
:expr $
(,)?
) => {
650 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
652 target
: TargetSelection
,
655 impl Step
for $tool
{
657 const DEFAULT
: bool
= true;
658 const ONLY_HOSTS
: bool
= true;
660 fn should_run(run
: ShouldRun
<'_
>) -> ShouldRun
<'_
> {
661 let builder
= run
.builder
;
662 run
.crate_or_deps($should_run
).default_condition(builder
.config
.compiler_docs
)
665 fn make_run(run
: RunConfig
<'_
>) {
666 run
.builder
.ensure($tool { target: run.target }
);
669 /// Generates compiler documentation.
671 /// This will generate all documentation for compiler and dependencies.
672 /// Compiler documentation is distributed separately, so we make sure
673 /// we do not merge it with the other documentation from std, test and
674 /// proc_macros. This is largely just a wrapper around `cargo doc`.
675 fn run(self, builder
: &Builder
<'_
>) {
676 let stage
= builder
.top_stage
;
677 let target
= self.target
;
679 // This is the intended out directory for compiler documentation.
680 let out
= builder
.compiler_doc_out(target
);
681 t
!(fs
::create_dir_all(&out
));
683 // Build rustc docs so that we generate relative links.
684 builder
.ensure(Rustc { stage, target }
);
685 // Rustdoc needs the rustc sysroot available to build.
686 // FIXME: is there a way to only ensure `check::Rustc` here? Last time I tried it failed
687 // with strange errors, but only on a full bors test ...
688 let compiler
= builder
.compiler(stage
, builder
.config
.build
);
689 builder
.ensure(compile
::Rustc
::new(compiler
, target
));
693 "Documenting stage{} {} ({})",
695 stringify
!($tool
).to_lowercase(),
700 // Symlink compiler docs to the output directory of rustdoc documentation.
701 let out_dir
= builder
.stage_out(compiler
, Mode
::ToolRustc
).join(target
.triple
).join("doc");
702 t
!(fs
::create_dir_all(&out_dir
));
703 t
!(symlink_dir_force(&builder
.config
, &out
, &out_dir
));
705 let source_type
= if $in_tree
== true {
708 SourceType
::Submodule
711 // Build cargo command.
712 let mut cargo
= prepare_tool_cargo(
723 cargo
.arg("-Zskip-rustdoc-fingerprint");
724 // Only include compiler crates, no dependencies of those, such as `libc`.
725 cargo
.arg("--no-deps");
727 cargo
.arg("-p").arg($krate
);
730 cargo
.rustdocflag("--document-private-items");
731 cargo
.rustdocflag("--enable-index-page");
732 cargo
.rustdocflag("--show-type-layout");
733 cargo
.rustdocflag("--generate-link-to-definition");
734 cargo
.rustdocflag("-Zunstable-options");
735 if $in_tree
== true {
736 builder
.run(&mut cargo
.into());
738 // Allow out-of-tree docs to fail (since the tool might be in a broken state).
739 if !builder
.try_run(&mut cargo
.into()) {
740 builder
.info(&format
!(
741 "WARNING: tool {} failed to document; ignoring failure because it is an out-of-tree tool",
742 stringify
!($tool
).to_lowercase(),
755 ["rustdoc", "rustdoc-json-types"],
762 ["rustfmt-nightly", "rustfmt-config_proc_macro"],
765 tool_doc
!(Clippy
, "clippy", "src/tools/clippy", ["clippy_utils"], in_tree
= true);
766 tool_doc
!(Miri
, "miri", "src/tools/miri", ["miri"], in_tree
= false);
768 #[derive(Ord, PartialOrd, Debug, Copy, Clone, Hash, PartialEq, Eq)]
769 pub struct ErrorIndex
{
770 pub target
: TargetSelection
,
773 impl Step
for ErrorIndex
{
775 const DEFAULT
: bool
= true;
776 const ONLY_HOSTS
: bool
= true;
778 fn should_run(run
: ShouldRun
<'_
>) -> ShouldRun
<'_
> {
779 let builder
= run
.builder
;
780 run
.path("src/tools/error_index_generator").default_condition(builder
.config
.docs
)
783 fn make_run(run
: RunConfig
<'_
>) {
784 let target
= run
.target
;
785 run
.builder
.ensure(ErrorIndex { target }
);
788 /// Generates the HTML rendered error-index by running the
789 /// `error_index_generator` tool.
790 fn run(self, builder
: &Builder
<'_
>) {
791 builder
.info(&format
!("Documenting error index ({})", self.target
));
792 let out
= builder
.doc_out(self.target
);
793 t
!(fs
::create_dir_all(&out
));
794 let mut index
= tool
::ErrorIndex
::command(builder
);
797 index
.arg(&builder
.version
);
799 builder
.run(&mut index
);
803 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
804 pub struct UnstableBookGen
{
805 target
: TargetSelection
,
808 impl Step
for UnstableBookGen
{
810 const DEFAULT
: bool
= true;
811 const ONLY_HOSTS
: bool
= true;
813 fn should_run(run
: ShouldRun
<'_
>) -> ShouldRun
<'_
> {
814 let builder
= run
.builder
;
815 run
.path("src/tools/unstable-book-gen").default_condition(builder
.config
.docs
)
818 fn make_run(run
: RunConfig
<'_
>) {
819 run
.builder
.ensure(UnstableBookGen { target: run.target }
);
822 fn run(self, builder
: &Builder
<'_
>) {
823 let target
= self.target
;
825 builder
.info(&format
!("Generating unstable book md files ({})", target
));
826 let out
= builder
.md_doc_out(target
).join("unstable-book");
827 builder
.create_dir(&out
);
828 builder
.remove_dir(&out
);
829 let mut cmd
= builder
.tool_cmd(Tool
::UnstableBookGen
);
830 cmd
.arg(builder
.src
.join("library"));
831 cmd
.arg(builder
.src
.join("compiler"));
832 cmd
.arg(builder
.src
.join("src"));
835 builder
.run(&mut cmd
);
839 fn symlink_dir_force(config
: &Config
, src
: &Path
, dst
: &Path
) -> io
::Result
<()> {
843 if let Ok(m
) = fs
::symlink_metadata(dst
) {
844 if m
.file_type().is_dir() {
845 fs
::remove_dir_all(dst
)?
;
847 // handle directory junctions on windows by falling back to
849 fs
::remove_file(dst
).or_else(|_
| fs
::remove_dir(dst
))?
;
853 symlink_dir(config
, src
, dst
)
856 #[derive(Ord, PartialOrd, Debug, Copy, Clone, Hash, PartialEq, Eq)]
857 pub struct RustcBook
{
858 pub compiler
: Compiler
,
859 pub target
: TargetSelection
,
863 impl Step
for RustcBook
{
865 const DEFAULT
: bool
= true;
866 const ONLY_HOSTS
: bool
= true;
868 fn should_run(run
: ShouldRun
<'_
>) -> ShouldRun
<'_
> {
869 let builder
= run
.builder
;
870 run
.path("src/doc/rustc").default_condition(builder
.config
.docs
)
873 fn make_run(run
: RunConfig
<'_
>) {
874 run
.builder
.ensure(RustcBook
{
875 compiler
: run
.builder
.compiler(run
.builder
.top_stage
, run
.builder
.config
.build
),
881 /// Builds the rustc book.
883 /// The lints are auto-generated by a tool, and then merged into the book
884 /// in the "md-doc" directory in the build output directory. Then
885 /// "rustbook" is used to convert it to HTML.
886 fn run(self, builder
: &Builder
<'_
>) {
887 let out_base
= builder
.md_doc_out(self.target
).join("rustc");
888 t
!(fs
::create_dir_all(&out_base
));
889 let out_listing
= out_base
.join("src/lints");
890 builder
.cp_r(&builder
.src
.join("src/doc/rustc"), &out_base
);
891 builder
.info(&format
!("Generating lint docs ({})", self.target
));
893 let rustc
= builder
.rustc(self.compiler
);
894 // The tool runs `rustc` for extracting output examples, so it needs a
895 // functional sysroot.
896 builder
.ensure(compile
::Std
::new(self.compiler
, self.target
));
897 let mut cmd
= builder
.tool_cmd(Tool
::LintDocs
);
899 cmd
.arg(builder
.src
.join("compiler"));
901 cmd
.arg(&out_listing
);
904 cmd
.arg("--rustc-target").arg(&self.target
.rustc_target_arg());
905 if builder
.config
.verbose() {
906 cmd
.arg("--verbose");
909 cmd
.arg("--validate");
911 if !builder
.unstable_features() {
912 // We need to validate nightly features, even on the stable channel.
913 cmd
.env("RUSTC_BOOTSTRAP", "1");
915 // If the lib directories are in an unusual location (changed in
916 // config.toml), then this needs to explicitly update the dylib search
918 builder
.add_rustc_lib_path(self.compiler
, &mut cmd
);
919 builder
.run(&mut cmd
);
920 // Run rustbook/mdbook to generate the HTML pages.
921 builder
.ensure(RustbookSrc
{
923 name
: INTERNER
.intern_str("rustc"),
924 src
: INTERNER
.intern_path(out_base
),
926 if builder
.was_invoked_explicitly
::<Self>(Kind
::Doc
) {
927 let out
= builder
.doc_out(self.target
);
928 let index
= out
.join("rustc").join("index.html");
929 open(builder
, &index
);