bootstrap/core/build_steps/
doc.rs

Help
1//! Documentation generation for bootstrap.
2//!
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.
6//!
7//! Everything here is basically just a shim around calling either `rustbook` or
8//! `rustdoc`.
9
10use std::io::{self, Write};
11use std::path::{Path, PathBuf};
12use std::{env, fs, mem};
13
14use crate::core::build_steps::compile;
15use crate::core::build_steps::tool::{self, SourceType, Tool, prepare_tool_cargo};
16use crate::core::builder::{
17    self, Alias, Builder, Compiler, Kind, RunConfig, ShouldRun, Step, crate_description,
18};
19use crate::core::config::{Config, TargetSelection};
20use crate::helpers::{submodule_path_of, symlink_dir, t, up_to_date};
21use crate::{FileType, Mode};
22
23macro_rules! book {
24    ($($name:ident, $path:expr, $book_name:expr, $lang:expr ;)+) => {
25        $(
26            #[derive(Debug, Clone, Hash, PartialEq, Eq)]
27        pub struct $name {
28            target: TargetSelection,
29        }
30
31        impl Step for $name {
32            type Output = ();
33            const DEFAULT: bool = true;
34
35            fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
36                let builder = run.builder;
37                run.path($path).default_condition(builder.config.docs)
38            }
39
40            fn make_run(run: RunConfig<'_>) {
41                run.builder.ensure($name {
42                    target: run.target,
43                });
44            }
45
46            fn run(self, builder: &Builder<'_>) {
47                if let Some(submodule_path) = submodule_path_of(&builder, $path) {
48                    builder.require_submodule(&submodule_path, None)
49                }
50
51                builder.ensure(RustbookSrc {
52                    target: self.target,
53                    name: $book_name.to_owned(),
54                    src: builder.src.join($path),
55                    parent: Some(self),
56                    languages: $lang.into(),
57                    rustdoc_compiler: None,
58                })
59            }
60        }
61        )+
62    }
63}
64
65// NOTE: When adding a book here, make sure to ALSO build the book by
66// adding a build step in `src/bootstrap/code/builder/mod.rs`!
67// NOTE: Make sure to add the corresponding submodule when adding a new book.
68book!(
69    CargoBook, "src/tools/cargo/src/doc", "cargo", &[];
70    ClippyBook, "src/tools/clippy/book", "clippy", &[];
71    EditionGuide, "src/doc/edition-guide", "edition-guide", &[];
72    EmbeddedBook, "src/doc/embedded-book", "embedded-book", &[];
73    Nomicon, "src/doc/nomicon", "nomicon", &[];
74    RustByExample, "src/doc/rust-by-example", "rust-by-example", &["ja", "zh"];
75    RustdocBook, "src/doc/rustdoc", "rustdoc", &[];
76    StyleGuide, "src/doc/style-guide", "style-guide", &[];
77);
78
79#[derive(Debug, Clone, Hash, PartialEq, Eq)]
80pub struct UnstableBook {
81    target: TargetSelection,
82}
83
84impl Step for UnstableBook {
85    type Output = ();
86    const DEFAULT: bool = true;
87
88    fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
89        let builder = run.builder;
90        run.path("src/doc/unstable-book").default_condition(builder.config.docs)
91    }
92
93    fn make_run(run: RunConfig<'_>) {
94        run.builder.ensure(UnstableBook { target: run.target });
95    }
96
97    fn run(self, builder: &Builder<'_>) {
98        builder.ensure(UnstableBookGen { target: self.target });
99        builder.ensure(RustbookSrc {
100            target: self.target,
101            name: "unstable-book".to_owned(),
102            src: builder.md_doc_out(self.target).join("unstable-book"),
103            parent: Some(self),
104            languages: vec![],
105            rustdoc_compiler: None,
106        })
107    }
108}
109
110#[derive(Debug, Clone, Hash, PartialEq, Eq)]
111struct RustbookSrc<P: Step> {
112    target: TargetSelection,
113    name: String,
114    src: PathBuf,
115    parent: Option<P>,
116    languages: Vec<&'static str>,
117    rustdoc_compiler: Option<Compiler>,
118}
119
120impl<P: Step> Step for RustbookSrc<P> {
121    type Output = ();
122
123    fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
124        run.never()
125    }
126
127    /// Invoke `rustbook` for `target` for the doc book `name` from the `src` path.
128    ///
129    /// This will not actually generate any documentation if the documentation has
130    /// already been generated.
131    fn run(self, builder: &Builder<'_>) {
132        let target = self.target;
133        let name = self.name;
134        let src = self.src;
135        let out = builder.doc_out(target);
136        t!(fs::create_dir_all(&out));
137
138        let out = out.join(&name);
139        let index = out.join("index.html");
140        let rustbook = builder.tool_exe(Tool::Rustbook);
141
142        if !builder.config.dry_run()
143            && (!up_to_date(&src, &index) || !up_to_date(&rustbook, &index))
144        {
145            builder.info(&format!("Rustbook ({target}) - {name}"));
146            let _ = fs::remove_dir_all(&out);
147
148            let mut rustbook_cmd = builder.tool_cmd(Tool::Rustbook);
149
150            if let Some(compiler) = self.rustdoc_compiler {
151                let mut rustdoc = builder.rustdoc(compiler);
152                rustdoc.pop();
153                let old_path = env::var_os("PATH").unwrap_or_default();
154                let new_path =
155                    env::join_paths(std::iter::once(rustdoc).chain(env::split_paths(&old_path)))
156                        .expect("could not add rustdoc to PATH");
157
158                rustbook_cmd.env("PATH", new_path);
159                builder.add_rustc_lib_path(compiler, &mut rustbook_cmd);
160            }
161
162            rustbook_cmd
163                .arg("build")
164                .arg(&src)
165                .arg("-d")
166                .arg(&out)
167                .arg("--rust-root")
168                .arg(&builder.src)
169                .run(builder);
170
171            for lang in &self.languages {
172                let out = out.join(lang);
173
174                builder.info(&format!("Rustbook ({target}) - {name} - {lang}"));
175                let _ = fs::remove_dir_all(&out);
176
177                builder
178                    .tool_cmd(Tool::Rustbook)
179                    .arg("build")
180                    .arg(&src)
181                    .arg("-d")
182                    .arg(&out)
183                    .arg("-l")
184                    .arg(lang)
185                    .run(builder);
186            }
187        }
188
189        if self.parent.is_some() {
190            builder.maybe_open_in_browser::<P>(index)
191        }
192    }
193}
194
195#[derive(Debug, Clone, Hash, PartialEq, Eq)]
196pub struct TheBook {
197    compiler: Compiler,
198    target: TargetSelection,
199}
200
201impl Step for TheBook {
202    type Output = ();
203    const DEFAULT: bool = true;
204
205    fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
206        let builder = run.builder;
207        run.path("src/doc/book").default_condition(builder.config.docs)
208    }
209
210    fn make_run(run: RunConfig<'_>) {
211        run.builder.ensure(TheBook {
212            compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
213            target: run.target,
214        });
215    }
216
217    /// Builds the book and associated stuff.
218    ///
219    /// We need to build:
220    ///
221    /// * Book
222    /// * Older edition redirects
223    /// * Version info and CSS
224    /// * Index page
225    /// * Redirect pages
226    fn run(self, builder: &Builder<'_>) {
227        builder.require_submodule("src/doc/book", None);
228
229        let compiler = self.compiler;
230        let target = self.target;
231
232        let absolute_path = builder.src.join("src/doc/book");
233        let redirect_path = absolute_path.join("redirects");
234
235        // build book
236        builder.ensure(RustbookSrc {
237            target,
238            name: "book".to_owned(),
239            src: absolute_path.clone(),
240            parent: Some(self),
241            languages: vec![],
242            rustdoc_compiler: None,
243        });
244
245        // building older edition redirects
246        for edition in &["first-edition", "second-edition", "2018-edition"] {
247            builder.ensure(RustbookSrc {
248                target,
249                name: format!("book/{edition}"),
250                src: absolute_path.join(edition),
251                // There should only be one book that is marked as the parent for each target, so
252                // treat the other editions as not having a parent.
253                parent: Option::<Self>::None,
254                languages: vec![],
255                rustdoc_compiler: None,
256            });
257        }
258
259        // build the version info page and CSS
260        let shared_assets = builder.ensure(SharedAssets { target });
261
262        // build the redirect pages
263        let _guard = builder.msg_doc(compiler, "book redirect pages", target);
264        for file in t!(fs::read_dir(redirect_path)) {
265            let file = t!(file);
266            let path = file.path();
267            let path = path.to_str().unwrap();
268
269            invoke_rustdoc(builder, compiler, &shared_assets, target, path);
270        }
271    }
272}
273
274fn invoke_rustdoc(
275    builder: &Builder<'_>,
276    compiler: Compiler,
277    shared_assets: &SharedAssetsPaths,
278    target: TargetSelection,
279    markdown: &str,
280) {
281    let out = builder.doc_out(target);
282
283    let path = builder.src.join("src/doc").join(markdown);
284
285    let header = builder.src.join("src/doc/redirect.inc");
286    let footer = builder.src.join("src/doc/footer.inc");
287
288    let mut cmd = builder.rustdoc_cmd(compiler);
289
290    let out = out.join("book");
291
292    cmd.arg("--html-after-content")
293        .arg(&footer)
294        .arg("--html-before-content")
295        .arg(&shared_assets.version_info)
296        .arg("--html-in-header")
297        .arg(&header)
298        .arg("--markdown-no-toc")
299        .arg("--markdown-playground-url")
300        .arg("https://play.rust-lang.org/")
301        .arg("-o")
302        .arg(&out)
303        .arg(&path)
304        .arg("--markdown-css")
305        .arg("../rust.css")
306        .arg("-Zunstable-options");
307
308    if !builder.config.docs_minification {
309        cmd.arg("--disable-minification");
310    }
311
312    cmd.run(builder);
313}
314
315#[derive(Debug, Clone, Hash, PartialEq, Eq)]
316pub struct Standalone {
317    compiler: Compiler,
318    target: TargetSelection,
319}
320
321impl Step for Standalone {
322    type Output = ();
323    const DEFAULT: bool = true;
324
325    fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
326        let builder = run.builder;
327        run.path("src/doc").alias("standalone").default_condition(builder.config.docs)
328    }
329
330    fn make_run(run: RunConfig<'_>) {
331        run.builder.ensure(Standalone {
332            compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
333            target: run.target,
334        });
335    }
336
337    /// Generates all standalone documentation as compiled by the rustdoc in `stage`
338    /// for the `target` into `out`.
339    ///
340    /// This will list all of `src/doc` looking for markdown files and appropriately
341    /// perform transformations like substituting `VERSION`, `SHORT_HASH`, and
342    /// `STAMP` along with providing the various header/footer HTML we've customized.
343    ///
344    /// In the end, this is just a glorified wrapper around rustdoc!
345    fn run(self, builder: &Builder<'_>) {
346        let target = self.target;
347        let compiler = self.compiler;
348        let _guard = builder.msg_doc(compiler, "standalone", target);
349        let out = builder.doc_out(target);
350        t!(fs::create_dir_all(&out));
351
352        let version_info = builder.ensure(SharedAssets { target: self.target }).version_info;
353
354        let favicon = builder.src.join("src/doc/favicon.inc");
355        let footer = builder.src.join("src/doc/footer.inc");
356        let full_toc = builder.src.join("src/doc/full-toc.inc");
357
358        for file in t!(fs::read_dir(builder.src.join("src/doc"))) {
359            let file = t!(file);
360            let path = file.path();
361            let filename = path.file_name().unwrap().to_str().unwrap();
362            if !filename.ends_with(".md") || filename == "README.md" {
363                continue;
364            }
365
366            let html = out.join(filename).with_extension("html");
367            let rustdoc = builder.rustdoc(compiler);
368            if up_to_date(&path, &html)
369                && up_to_date(&footer, &html)
370                && up_to_date(&favicon, &html)
371                && up_to_date(&full_toc, &html)
372                && (builder.config.dry_run() || up_to_date(&version_info, &html))
373                && (builder.config.dry_run() || up_to_date(&rustdoc, &html))
374            {
375                continue;
376            }
377
378            let mut cmd = builder.rustdoc_cmd(compiler);
379
380            cmd.arg("--html-after-content")
381                .arg(&footer)
382                .arg("--html-before-content")
383                .arg(&version_info)
384                .arg("--html-in-header")
385                .arg(&favicon)
386                .arg("--markdown-no-toc")
387                .arg("-Zunstable-options")
388                .arg("--index-page")
389                .arg(builder.src.join("src/doc/index.md"))
390                .arg("--markdown-playground-url")
391                .arg("https://play.rust-lang.org/")
392                .arg("-o")
393                .arg(&out)
394                .arg(&path);
395
396            if !builder.config.docs_minification {
397                cmd.arg("--disable-minification");
398            }
399
400            if filename == "not_found.md" {
401                cmd.arg("--markdown-css").arg("https://doc.rust-lang.org/rust.css");
402            } else {
403                cmd.arg("--markdown-css").arg("rust.css");
404            }
405            cmd.run(builder);
406        }
407
408        // We open doc/index.html as the default if invoked as `x.py doc --open`
409        // with no particular explicit doc requested (e.g. library/core).
410        if builder.paths.is_empty() || builder.was_invoked_explicitly::<Self>(Kind::Doc) {
411            let index = out.join("index.html");
412            builder.open_in_browser(index);
413        }
414    }
415}
416
417#[derive(Debug, Clone, Hash, PartialEq, Eq)]
418pub struct Releases {
419    compiler: Compiler,
420    target: TargetSelection,
421}
422
423impl Step for Releases {
424    type Output = ();
425    const DEFAULT: bool = true;
426
427    fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
428        let builder = run.builder;
429        run.path("RELEASES.md").alias("releases").default_condition(builder.config.docs)
430    }
431
432    fn make_run(run: RunConfig<'_>) {
433        run.builder.ensure(Releases {
434            compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
435            target: run.target,
436        });
437    }
438
439    /// Generates HTML release notes to include in the final docs bundle.
440    ///
441    /// This uses the same stylesheet and other tools as Standalone, but the
442    /// RELEASES.md file is included at the root of the repository and gets
443    /// the headline added. In the end, the conversion is done by Rustdoc.
444    fn run(self, builder: &Builder<'_>) {
445        let target = self.target;
446        let compiler = self.compiler;
447        let _guard = builder.msg_doc(compiler, "releases", target);
448        let out = builder.doc_out(target);
449        t!(fs::create_dir_all(&out));
450
451        builder.ensure(Standalone {
452            compiler: builder.compiler(builder.top_stage, builder.config.build),
453            target,
454        });
455
456        let version_info = builder.ensure(SharedAssets { target: self.target }).version_info;
457
458        let favicon = builder.src.join("src/doc/favicon.inc");
459        let footer = builder.src.join("src/doc/footer.inc");
460        let full_toc = builder.src.join("src/doc/full-toc.inc");
461
462        let html = out.join("releases.html");
463        let tmppath = out.join("releases.md");
464        let inpath = builder.src.join("RELEASES.md");
465        let rustdoc = builder.rustdoc(compiler);
466        if !up_to_date(&inpath, &html)
467            || !up_to_date(&footer, &html)
468            || !up_to_date(&favicon, &html)
469            || !up_to_date(&full_toc, &html)
470            || !(builder.config.dry_run()
471                || up_to_date(&version_info, &html)
472                || up_to_date(&rustdoc, &html))
473        {
474            let mut tmpfile = t!(fs::File::create(&tmppath));
475            t!(tmpfile.write_all(b"% Rust Release Notes\n\n"));
476            t!(io::copy(&mut t!(fs::File::open(&inpath)), &mut tmpfile));
477            mem::drop(tmpfile);
478            let mut cmd = builder.rustdoc_cmd(compiler);
479
480            cmd.arg("--html-after-content")
481                .arg(&footer)
482                .arg("--html-before-content")
483                .arg(&version_info)
484                .arg("--html-in-header")
485                .arg(&favicon)
486                .arg("--markdown-no-toc")
487                .arg("--markdown-css")
488                .arg("rust.css")
489                .arg("-Zunstable-options")
490                .arg("--index-page")
491                .arg(builder.src.join("src/doc/index.md"))
492                .arg("--markdown-playground-url")
493                .arg("https://play.rust-lang.org/")
494                .arg("-o")
495                .arg(&out)
496                .arg(&tmppath);
497
498            if !builder.config.docs_minification {
499                cmd.arg("--disable-minification");
500            }
501
502            cmd.run(builder);
503        }
504
505        // We open doc/RELEASES.html as the default if invoked as `x.py doc --open RELEASES.md`
506        // with no particular explicit doc requested (e.g. library/core).
507        if builder.was_invoked_explicitly::<Self>(Kind::Doc) {
508            builder.open_in_browser(&html);
509        }
510    }
511}
512
513#[derive(Debug, Clone)]
514pub struct SharedAssetsPaths {
515    pub version_info: PathBuf,
516}
517
518#[derive(Debug, Clone, Hash, PartialEq, Eq)]
519pub struct SharedAssets {
520    target: TargetSelection,
521}
522
523impl Step for SharedAssets {
524    type Output = SharedAssetsPaths;
525    const DEFAULT: bool = false;
526
527    fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
528        // Other tasks depend on this, no need to execute it on its own
529        run.never()
530    }
531
532    /// Generate shared resources used by other pieces of documentation.
533    fn run(self, builder: &Builder<'_>) -> Self::Output {
534        let out = builder.doc_out(self.target);
535
536        let version_input = builder.src.join("src").join("doc").join("version_info.html.template");
537        let version_info = out.join("version_info.html");
538        if !builder.config.dry_run() && !up_to_date(&version_input, &version_info) {
539            let info = t!(fs::read_to_string(&version_input))
540                .replace("VERSION", &builder.rust_release())
541                .replace("SHORT_HASH", builder.rust_info().sha_short().unwrap_or(""))
542                .replace("STAMP", builder.rust_info().sha().unwrap_or(""));
543            t!(fs::write(&version_info, info));
544        }
545
546        builder.copy_link(
547            &builder.src.join("src").join("doc").join("rust.css"),
548            &out.join("rust.css"),
549            FileType::Regular,
550        );
551
552        SharedAssetsPaths { version_info }
553    }
554}
555
556#[derive(Debug, Clone, Hash, PartialEq, Eq, PartialOrd, Ord)]
557pub struct Std {
558    pub stage: u32,
559    pub target: TargetSelection,
560    pub format: DocumentationFormat,
561    crates: Vec<String>,
562}
563
564impl Std {
565    pub(crate) fn new(stage: u32, target: TargetSelection, format: DocumentationFormat) -> Self {
566        Std { stage, target, format, crates: vec![] }
567    }
568}
569
570impl Step for Std {
571    type Output = ();
572    const DEFAULT: bool = true;
573
574    fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
575        let builder = run.builder;
576        run.crate_or_deps("sysroot").path("library").default_condition(builder.config.docs)
577    }
578
579    fn make_run(run: RunConfig<'_>) {
580        let crates = compile::std_crates_for_run_make(&run);
581        let target_is_no_std = run.builder.no_std(run.target).unwrap_or(false);
582        if crates.is_empty() && target_is_no_std {
583            return;
584        }
585        run.builder.ensure(Std {
586            stage: run.builder.top_stage,
587            target: run.target,
588            format: if run.builder.config.cmd.json() {
589                DocumentationFormat::Json
590            } else {
591                DocumentationFormat::Html
592            },
593            crates,
594        });
595    }
596
597    /// Compile all standard library documentation.
598    ///
599    /// This will generate all documentation for the standard library and its
600    /// dependencies. This is largely just a wrapper around `cargo doc`.
601    fn run(self, builder: &Builder<'_>) {
602        let stage = self.stage;
603        let target = self.target;
604        let crates = if self.crates.is_empty() {
605            builder
606                .in_tree_crates("sysroot", Some(target))
607                .iter()
608                .map(|c| c.name.to_string())
609                .collect()
610        } else {
611            self.crates
612        };
613
614        let out = match self.format {
615            DocumentationFormat::Html => builder.doc_out(target),
616            DocumentationFormat::Json => builder.json_doc_out(target),
617        };
618
619        t!(fs::create_dir_all(&out));
620
621        if self.format == DocumentationFormat::Html {
622            builder.ensure(SharedAssets { target: self.target });
623        }
624
625        let index_page = builder
626            .src
627            .join("src/doc/index.md")
628            .into_os_string()
629            .into_string()
630            .expect("non-utf8 paths are unsupported");
631        let mut extra_args = match self.format {
632            DocumentationFormat::Html => {
633                vec!["--markdown-css", "rust.css", "--markdown-no-toc", "--index-page", &index_page]
634            }
635            DocumentationFormat::Json => vec!["--output-format", "json"],
636        };
637
638        if !builder.config.docs_minification {
639            extra_args.push("--disable-minification");
640        }
641        // For `--index-page` and `--output-format=json`.
642        extra_args.push("-Zunstable-options");
643
644        doc_std(builder, self.format, stage, target, &out, &extra_args, &crates);
645
646        // Don't open if the format is json
647        if let DocumentationFormat::Json = self.format {
648            return;
649        }
650
651        if builder.paths.iter().any(|path| path.ends_with("library")) {
652            // For `x.py doc library --open`, open `std` by default.
653            let index = out.join("std").join("index.html");
654            builder.open_in_browser(index);
655        } else {
656            for requested_crate in crates {
657                if STD_PUBLIC_CRATES.iter().any(|&k| k == requested_crate) {
658                    let index = out.join(requested_crate).join("index.html");
659                    builder.open_in_browser(index);
660                    break;
661                }
662            }
663        }
664    }
665}
666
667/// Name of the crates that are visible to consumers of the standard library.
668/// Documentation for internal crates is handled by the rustc step, so internal crates will show
669/// up there.
670///
671/// Order here is important!
672/// Crates need to be processed starting from the leaves, otherwise rustdoc will not
673/// create correct links between crates because rustdoc depends on the
674/// existence of the output directories to know if it should be a local
675/// or remote link.
676const STD_PUBLIC_CRATES: [&str; 5] = ["core", "alloc", "std", "proc_macro", "test"];
677
678#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq, PartialOrd, Ord)]
679pub enum DocumentationFormat {
680    Html,
681    Json,
682}
683
684impl DocumentationFormat {
685    fn as_str(&self) -> &str {
686        match self {
687            DocumentationFormat::Html => "HTML",
688            DocumentationFormat::Json => "JSON",
689        }
690    }
691}
692
693/// Build the documentation for public standard library crates.
694fn doc_std(
695    builder: &Builder<'_>,
696    format: DocumentationFormat,
697    stage: u32,
698    target: TargetSelection,
699    out: &Path,
700    extra_args: &[&str],
701    requested_crates: &[String],
702) {
703    let compiler = builder.compiler(stage, builder.config.build);
704
705    let target_doc_dir_name = if format == DocumentationFormat::Json { "json-doc" } else { "doc" };
706    let target_dir = builder.stage_out(compiler, Mode::Std).join(target).join(target_doc_dir_name);
707
708    // This is directory where the compiler will place the output of the command.
709    // We will then copy the files from this directory into the final `out` directory, the specified
710    // as a function parameter.
711    let out_dir = target_dir.join(target).join("doc");
712
713    let mut cargo =
714        builder::Cargo::new(builder, compiler, Mode::Std, SourceType::InTree, target, Kind::Doc);
715
716    compile::std_cargo(builder, target, compiler.stage, &mut cargo);
717    cargo
718        .arg("--no-deps")
719        .arg("--target-dir")
720        .arg(&*target_dir.to_string_lossy())
721        .arg("-Zskip-rustdoc-fingerprint")
722        .arg("-Zrustdoc-map")
723        .rustdocflag("--extern-html-root-url")
724        .rustdocflag("std_detect=https://docs.rs/std_detect/latest/")
725        .rustdocflag("--extern-html-root-takes-precedence")
726        .rustdocflag("--resource-suffix")
727        .rustdocflag(&builder.version);
728    for arg in extra_args {
729        cargo.rustdocflag(arg);
730    }
731
732    if builder.config.library_docs_private_items {
733        cargo.rustdocflag("--document-private-items").rustdocflag("--document-hidden-items");
734    }
735
736    for krate in requested_crates {
737        if krate == "sysroot" {
738            // The sysroot crate is an implementation detail, don't include it in public docs.
739            continue;
740        }
741        cargo.arg("-p").arg(krate);
742    }
743
744    let description =
745        format!("library{} in {} format", crate_description(requested_crates), format.as_str());
746    let _guard = builder.msg_doc(compiler, description, target);
747
748    cargo.into_cmd().run(builder);
749    builder.cp_link_r(&out_dir, out);
750}
751
752#[derive(Debug, Clone, Hash, PartialEq, Eq)]
753pub struct Rustc {
754    pub stage: u32,
755    pub target: TargetSelection,
756    crates: Vec<String>,
757}
758
759impl Rustc {
760    pub(crate) fn new(stage: u32, target: TargetSelection, builder: &Builder<'_>) -> Self {
761        let crates = builder
762            .in_tree_crates("rustc-main", Some(target))
763            .into_iter()
764            .map(|krate| krate.name.to_string())
765            .collect();
766        Self { stage, target, crates }
767    }
768}
769
770impl Step for Rustc {
771    type Output = ();
772    const DEFAULT: bool = true;
773    const ONLY_HOSTS: bool = true;
774
775    fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
776        let builder = run.builder;
777        run.crate_or_deps("rustc-main")
778            .path("compiler")
779            .default_condition(builder.config.compiler_docs)
780    }
781
782    fn make_run(run: RunConfig<'_>) {
783        run.builder.ensure(Rustc {
784            stage: run.builder.top_stage,
785            target: run.target,
786            crates: run.make_run_crates(Alias::Compiler),
787        });
788    }
789
790    /// Generates compiler documentation.
791    ///
792    /// This will generate all documentation for compiler and dependencies.
793    /// Compiler documentation is distributed separately, so we make sure
794    /// we do not merge it with the other documentation from std, test and
795    /// proc_macros. This is largely just a wrapper around `cargo doc`.
796    fn run(self, builder: &Builder<'_>) {
797        let stage = self.stage;
798        let target = self.target;
799
800        // This is the intended out directory for compiler documentation.
801        let out = builder.compiler_doc_out(target);
802        t!(fs::create_dir_all(&out));
803
804        // Build the standard library, so that proc-macros can use it.
805        // (Normally, only the metadata would be necessary, but proc-macros are special since they run at compile-time.)
806        let compiler = builder.compiler(stage, builder.config.build);
807        builder.ensure(compile::Std::new(compiler, builder.config.build));
808
809        let _guard = builder.msg_sysroot_tool(
810            Kind::Doc,
811            stage,
812            format!("compiler{}", crate_description(&self.crates)),
813            compiler.host,
814            target,
815        );
816
817        // Build cargo command.
818        let mut cargo = builder::Cargo::new(
819            builder,
820            compiler,
821            Mode::Rustc,
822            SourceType::InTree,
823            target,
824            Kind::Doc,
825        );
826
827        cargo.rustdocflag("--document-private-items");
828        // Since we always pass --document-private-items, there's no need to warn about linking to private items.
829        cargo.rustdocflag("-Arustdoc::private-intra-doc-links");
830        cargo.rustdocflag("--enable-index-page");
831        cargo.rustdocflag("-Znormalize-docs");
832        cargo.rustdocflag("--show-type-layout");
833        // FIXME: `--generate-link-to-definition` tries to resolve cfged out code
834        // see https://github.com/rust-lang/rust/pull/122066#issuecomment-1983049222
835        // If there is any bug, please comment out the next line.
836        cargo.rustdocflag("--generate-link-to-definition");
837
838        compile::rustc_cargo(builder, &mut cargo, target, &compiler, &self.crates);
839        cargo.arg("-Zskip-rustdoc-fingerprint");
840
841        // Only include compiler crates, no dependencies of those, such as `libc`.
842        // Do link to dependencies on `docs.rs` however using `rustdoc-map`.
843        cargo.arg("--no-deps");
844        cargo.arg("-Zrustdoc-map");
845
846        // FIXME: `-Zrustdoc-map` does not yet correctly work for transitive dependencies,
847        // once this is no longer an issue the special case for `ena` can be removed.
848        cargo.rustdocflag("--extern-html-root-url");
849        cargo.rustdocflag("ena=https://docs.rs/ena/latest/");
850
851        let mut to_open = None;
852
853        let out_dir = builder.stage_out(compiler, Mode::Rustc).join(target).join("doc");
854        for krate in &*self.crates {
855            // Create all crate output directories first to make sure rustdoc uses
856            // relative links.
857            // FIXME: Cargo should probably do this itself.
858            let dir_name = krate.replace('-', "_");
859            t!(fs::create_dir_all(out_dir.join(&*dir_name)));
860            cargo.arg("-p").arg(krate);
861            if to_open.is_none() {
862                to_open = Some(dir_name);
863            }
864        }
865
866        // This uses a shared directory so that librustdoc documentation gets
867        // correctly built and merged with the rustc documentation.
868        //
869        // This is needed because rustdoc is built in a different directory from
870        // rustc. rustdoc needs to be able to see everything, for example when
871        // merging the search index, or generating local (relative) links.
872        symlink_dir_force(&builder.config, &out, &out_dir);
873        // Cargo puts proc macros in `target/doc` even if you pass `--target`
874        // explicitly (https://github.com/rust-lang/cargo/issues/7677).
875        let proc_macro_out_dir = builder.stage_out(compiler, Mode::Rustc).join("doc");
876        symlink_dir_force(&builder.config, &out, &proc_macro_out_dir);
877
878        cargo.into_cmd().run(builder);
879
880        if !builder.config.dry_run() {
881            // Sanity check on linked compiler crates
882            for krate in &*self.crates {
883                let dir_name = krate.replace('-', "_");
884                // Making sure the directory exists and is not empty.
885                assert!(out.join(&*dir_name).read_dir().unwrap().next().is_some());
886            }
887        }
888
889        if builder.paths.iter().any(|path| path.ends_with("compiler")) {
890            // For `x.py doc compiler --open`, open `rustc_middle` by default.
891            let index = out.join("rustc_middle").join("index.html");
892            builder.open_in_browser(index);
893        } else if let Some(krate) = to_open {
894            // Let's open the first crate documentation page:
895            let index = out.join(krate).join("index.html");
896            builder.open_in_browser(index);
897        }
898    }
899}
900
901macro_rules! tool_doc {
902    (
903        $tool: ident,
904        $path: literal,
905        $(rustc_tool = $rustc_tool:literal, )?
906        $(is_library = $is_library:expr,)?
907        $(crates = $crates:expr)?
908       ) => {
909        #[derive(Debug, Clone, Hash, PartialEq, Eq)]
910        pub struct $tool {
911            target: TargetSelection,
912        }
913
914        impl Step for $tool {
915            type Output = ();
916            const DEFAULT: bool = true;
917            const ONLY_HOSTS: bool = true;
918
919            fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
920                let builder = run.builder;
921                run.path($path).default_condition(builder.config.compiler_docs)
922            }
923
924            fn make_run(run: RunConfig<'_>) {
925                run.builder.ensure($tool { target: run.target });
926            }
927
928            /// Generates compiler documentation.
929            ///
930            /// This will generate all documentation for compiler and dependencies.
931            /// Compiler documentation is distributed separately, so we make sure
932            /// we do not merge it with the other documentation from std, test and
933            /// proc_macros. This is largely just a wrapper around `cargo doc`.
934            fn run(self, builder: &Builder<'_>) {
935                let mut source_type = SourceType::InTree;
936
937                if let Some(submodule_path) = submodule_path_of(&builder, $path) {
938                    source_type = SourceType::Submodule;
939                    builder.require_submodule(&submodule_path, None);
940                }
941
942                let stage = builder.top_stage;
943                let target = self.target;
944
945                // This is the intended out directory for compiler documentation.
946                let out = builder.compiler_doc_out(target);
947                t!(fs::create_dir_all(&out));
948
949                let compiler = builder.compiler(stage, builder.config.build);
950                builder.ensure(compile::Std::new(compiler, target));
951
952                if true $(&& $rustc_tool)? {
953                    // Build rustc docs so that we generate relative links.
954                    builder.ensure(Rustc::new(stage, target, builder));
955
956                    // Rustdoc needs the rustc sysroot available to build.
957                    // FIXME: is there a way to only ensure `check::Rustc` here? Last time I tried it failed
958                    // with strange errors, but only on a full bors test ...
959                    builder.ensure(compile::Rustc::new(compiler, target));
960                }
961
962                // Build cargo command.
963                let mut cargo = prepare_tool_cargo(
964                    builder,
965                    compiler,
966                    Mode::ToolRustc,
967                    target,
968                    Kind::Doc,
969                    $path,
970                    source_type,
971                    &[],
972                );
973
974                cargo.arg("-Zskip-rustdoc-fingerprint");
975                // Only include compiler crates, no dependencies of those, such as `libc`.
976                cargo.arg("--no-deps");
977
978                if false $(|| $is_library)? {
979                    cargo.arg("--lib");
980                }
981
982                $(for krate in $crates {
983                    cargo.arg("-p").arg(krate);
984                })?
985
986                cargo.rustdocflag("--document-private-items");
987                // Since we always pass --document-private-items, there's no need to warn about linking to private items.
988                cargo.rustdocflag("-Arustdoc::private-intra-doc-links");
989                cargo.rustdocflag("--enable-index-page");
990                cargo.rustdocflag("--show-type-layout");
991                cargo.rustdocflag("--generate-link-to-definition");
992
993                let out_dir = builder.stage_out(compiler, Mode::ToolRustc).join(target).join("doc");
994                $(for krate in $crates {
995                    let dir_name = krate.replace("-", "_");
996                    t!(fs::create_dir_all(out_dir.join(&*dir_name)));
997                })?
998
999                // Symlink compiler docs to the output directory of rustdoc documentation.
1000                symlink_dir_force(&builder.config, &out, &out_dir);
1001                let proc_macro_out_dir = builder.stage_out(compiler, Mode::ToolRustc).join("doc");
1002                symlink_dir_force(&builder.config, &out, &proc_macro_out_dir);
1003
1004                let _guard = builder.msg_doc(compiler, stringify!($tool).to_lowercase(), target);
1005                cargo.into_cmd().run(builder);
1006
1007                if !builder.config.dry_run() {
1008                    // Sanity check on linked doc directories
1009                    $(for krate in $crates {
1010                        let dir_name = krate.replace("-", "_");
1011                        // Making sure the directory exists and is not empty.
1012                        assert!(out.join(&*dir_name).read_dir().unwrap().next().is_some());
1013                    })?
1014                }
1015            }
1016        }
1017    }
1018}
1019
1020// NOTE: make sure to register these in `Builder::get_step_description`.
1021tool_doc!(
1022    BuildHelper,
1023    "src/build_helper",
1024    rustc_tool = false,
1025    is_library = true,
1026    crates = ["build_helper"]
1027);
1028tool_doc!(Rustdoc, "src/tools/rustdoc", crates = ["rustdoc", "rustdoc-json-types"]);
1029tool_doc!(Rustfmt, "src/tools/rustfmt", crates = ["rustfmt-nightly", "rustfmt-config_proc_macro"]);
1030tool_doc!(Clippy, "src/tools/clippy", crates = ["clippy_config", "clippy_utils"]);
1031tool_doc!(Miri, "src/tools/miri", crates = ["miri"]);
1032tool_doc!(
1033    Cargo,
1034    "src/tools/cargo",
1035    rustc_tool = false,
1036    crates = [
1037        "cargo",
1038        "cargo-credential",
1039        "cargo-platform",
1040        "cargo-test-macro",
1041        "cargo-test-support",
1042        "cargo-util",
1043        "cargo-util-schemas",
1044        "crates-io",
1045        "mdman",
1046        "rustfix",
1047    ]
1048);
1049tool_doc!(Tidy, "src/tools/tidy", rustc_tool = false, crates = ["tidy"]);
1050tool_doc!(
1051    Bootstrap,
1052    "src/bootstrap",
1053    rustc_tool = false,
1054    is_library = true,
1055    crates = ["bootstrap"]
1056);
1057tool_doc!(
1058    RunMakeSupport,
1059    "src/tools/run-make-support",
1060    rustc_tool = false,
1061    is_library = true,
1062    crates = ["run_make_support"]
1063);
1064tool_doc!(
1065    Compiletest,
1066    "src/tools/compiletest",
1067    rustc_tool = false,
1068    is_library = true,
1069    crates = ["compiletest"]
1070);
1071
1072#[derive(Ord, PartialOrd, Debug, Clone, Hash, PartialEq, Eq)]
1073pub struct ErrorIndex {
1074    pub target: TargetSelection,
1075}
1076
1077impl Step for ErrorIndex {
1078    type Output = ();
1079    const DEFAULT: bool = true;
1080    const ONLY_HOSTS: bool = true;
1081
1082    fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
1083        let builder = run.builder;
1084        run.path("src/tools/error_index_generator").default_condition(builder.config.docs)
1085    }
1086
1087    fn make_run(run: RunConfig<'_>) {
1088        let target = run.target;
1089        run.builder.ensure(ErrorIndex { target });
1090    }
1091
1092    /// Generates the HTML rendered error-index by running the
1093    /// `error_index_generator` tool.
1094    fn run(self, builder: &Builder<'_>) {
1095        builder.info(&format!("Documenting error index ({})", self.target));
1096        let out = builder.doc_out(self.target);
1097        t!(fs::create_dir_all(&out));
1098        tool::ErrorIndex::command(builder).arg("html").arg(out).arg(&builder.version).run(builder);
1099    }
1100}
1101
1102#[derive(Debug, Clone, Hash, PartialEq, Eq)]
1103pub struct UnstableBookGen {
1104    target: TargetSelection,
1105}
1106
1107impl Step for UnstableBookGen {
1108    type Output = ();
1109    const DEFAULT: bool = true;
1110    const ONLY_HOSTS: bool = true;
1111
1112    fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
1113        let builder = run.builder;
1114        run.path("src/tools/unstable-book-gen").default_condition(builder.config.docs)
1115    }
1116
1117    fn make_run(run: RunConfig<'_>) {
1118        run.builder.ensure(UnstableBookGen { target: run.target });
1119    }
1120
1121    fn run(self, builder: &Builder<'_>) {
1122        let target = self.target;
1123
1124        builder.info(&format!("Generating unstable book md files ({target})"));
1125        let out = builder.md_doc_out(target).join("unstable-book");
1126        builder.create_dir(&out);
1127        builder.remove_dir(&out);
1128        let mut cmd = builder.tool_cmd(Tool::UnstableBookGen);
1129        cmd.arg(builder.src.join("library"));
1130        cmd.arg(builder.src.join("compiler"));
1131        cmd.arg(builder.src.join("src"));
1132        cmd.arg(out);
1133
1134        cmd.run(builder);
1135    }
1136}
1137
1138fn symlink_dir_force(config: &Config, original: &Path, link: &Path) {
1139    if config.dry_run() {
1140        return;
1141    }
1142    if let Ok(m) = fs::symlink_metadata(link) {
1143        if m.file_type().is_dir() {
1144            t!(fs::remove_dir_all(link));
1145        } else {
1146            // handle directory junctions on windows by falling back to
1147            // `remove_dir`.
1148            t!(fs::remove_file(link).or_else(|_| fs::remove_dir(link)));
1149        }
1150    }
1151
1152    t!(
1153        symlink_dir(config, original, link),
1154        format!("failed to create link from {} -> {}", link.display(), original.display())
1155    );
1156}
1157
1158#[derive(Ord, PartialOrd, Debug, Clone, Hash, PartialEq, Eq)]
1159pub struct RustcBook {
1160    pub compiler: Compiler,
1161    pub target: TargetSelection,
1162    pub validate: bool,
1163}
1164
1165impl Step for RustcBook {
1166    type Output = ();
1167    const DEFAULT: bool = true;
1168    const ONLY_HOSTS: bool = true;
1169
1170    fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
1171        let builder = run.builder;
1172        run.path("src/doc/rustc").default_condition(builder.config.docs)
1173    }
1174
1175    fn make_run(run: RunConfig<'_>) {
1176        run.builder.ensure(RustcBook {
1177            compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
1178            target: run.target,
1179            validate: false,
1180        });
1181    }
1182
1183    /// Builds the rustc book.
1184    ///
1185    /// The lints are auto-generated by a tool, and then merged into the book
1186    /// in the "md-doc" directory in the build output directory. Then
1187    /// "rustbook" is used to convert it to HTML.
1188    fn run(self, builder: &Builder<'_>) {
1189        let out_base = builder.md_doc_out(self.target).join("rustc");
1190        t!(fs::create_dir_all(&out_base));
1191        let out_listing = out_base.join("src/lints");
1192        builder.cp_link_r(&builder.src.join("src/doc/rustc"), &out_base);
1193        builder.info(&format!("Generating lint docs ({})", self.target));
1194
1195        let rustc = builder.rustc(self.compiler);
1196        // The tool runs `rustc` for extracting output examples, so it needs a
1197        // functional sysroot.
1198        builder.ensure(compile::Std::new(self.compiler, self.target));
1199        let mut cmd = builder.tool_cmd(Tool::LintDocs);
1200        cmd.arg("--src");
1201        cmd.arg(builder.src.join("compiler"));
1202        cmd.arg("--out");
1203        cmd.arg(&out_listing);
1204        cmd.arg("--rustc");
1205        cmd.arg(&rustc);
1206        cmd.arg("--rustc-target").arg(self.target.rustc_target_arg());
1207        if let Some(target_linker) = builder.linker(self.target) {
1208            cmd.arg("--rustc-linker").arg(target_linker);
1209        }
1210        if builder.is_verbose() {
1211            cmd.arg("--verbose");
1212        }
1213        if self.validate {
1214            cmd.arg("--validate");
1215        }
1216        // We need to validate nightly features, even on the stable channel.
1217        // Set this unconditionally as the stage0 compiler may be being used to
1218        // document.
1219        cmd.env("RUSTC_BOOTSTRAP", "1");
1220
1221        // If the lib directories are in an unusual location (changed in
1222        // bootstrap.toml), then this needs to explicitly update the dylib search
1223        // path.
1224        builder.add_rustc_lib_path(self.compiler, &mut cmd);
1225        let doc_generator_guard = builder.msg(
1226            Kind::Run,
1227            self.compiler.stage,
1228            "lint-docs",
1229            self.compiler.host,
1230            self.target,
1231        );
1232        cmd.run(builder);
1233        drop(doc_generator_guard);
1234
1235        // Run rustbook/mdbook to generate the HTML pages.
1236        builder.ensure(RustbookSrc {
1237            target: self.target,
1238            name: "rustc".to_owned(),
1239            src: out_base,
1240            parent: Some(self),
1241            languages: vec![],
1242            rustdoc_compiler: None,
1243        });
1244    }
1245}
1246
1247#[derive(Ord, PartialOrd, Debug, Clone, Hash, PartialEq, Eq)]
1248pub struct Reference {
1249    pub compiler: Compiler,
1250    pub target: TargetSelection,
1251}
1252
1253impl Step for Reference {
1254    type Output = ();
1255    const DEFAULT: bool = true;
1256
1257    fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
1258        let builder = run.builder;
1259        run.path("src/doc/reference").default_condition(builder.config.docs)
1260    }
1261
1262    fn make_run(run: RunConfig<'_>) {
1263        run.builder.ensure(Reference {
1264            compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
1265            target: run.target,
1266        });
1267    }
1268
1269    /// Builds the reference book.
1270    fn run(self, builder: &Builder<'_>) {
1271        builder.require_submodule("src/doc/reference", None);
1272
1273        // This is needed for generating links to the standard library using
1274        // the mdbook-spec plugin.
1275        builder.ensure(compile::Std::new(self.compiler, builder.config.build));
1276
1277        // Run rustbook/mdbook to generate the HTML pages.
1278        builder.ensure(RustbookSrc {
1279            target: self.target,
1280            name: "reference".to_owned(),
1281            src: builder.src.join("src/doc/reference"),
1282            rustdoc_compiler: Some(self.compiler),
1283            parent: Some(self),
1284            languages: vec![],
1285        });
1286    }
1287}
bootstrap/core/build_steps/doc.rs

bootstrap/core/build_steps/
doc.rs
