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::Mode;
15use crate::core::build_steps::compile;
16use crate::core::build_steps::tool::{self, SourceType, Tool, prepare_tool_cargo};
17use crate::core::builder::{
18    self, Alias, Builder, Compiler, Kind, RunConfig, ShouldRun, Step, crate_description,
19};
20use crate::core::config::{Config, TargetSelection};
21use crate::helpers::{submodule_path_of, symlink_dir, t, up_to_date};
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        );
550
551        SharedAssetsPaths { version_info }
552    }
553}
554
555#[derive(Debug, Clone, Hash, PartialEq, Eq, PartialOrd, Ord)]
556pub struct Std {
557    pub stage: u32,
558    pub target: TargetSelection,
559    pub format: DocumentationFormat,
560    crates: Vec<String>,
561}
562
563impl Std {
564    pub(crate) fn new(stage: u32, target: TargetSelection, format: DocumentationFormat) -> Self {
565        Std { stage, target, format, crates: vec![] }
566    }
567}
568
569impl Step for Std {
570    type Output = ();
571    const DEFAULT: bool = true;
572
573    fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
574        let builder = run.builder;
575        run.crate_or_deps("sysroot")
576            .path("library")
577            .alias("core")
578            .default_condition(builder.config.docs)
579    }
580
581    fn make_run(run: RunConfig<'_>) {
582        let crates = compile::std_crates_for_run_make(&run);
583        run.builder.ensure(Std {
584            stage: run.builder.top_stage,
585            target: run.target,
586            format: if run.builder.config.cmd.json() {
587                DocumentationFormat::Json
588            } else {
589                DocumentationFormat::Html
590            },
591            crates,
592        });
593    }
594
595    /// Compile all standard library documentation.
596    ///
597    /// This will generate all documentation for the standard library and its
598    /// dependencies. This is largely just a wrapper around `cargo doc`.
599    fn run(self, builder: &Builder<'_>) {
600        let stage = self.stage;
601        let target = self.target;
602        let crates = if self.crates.is_empty() {
603            builder
604                .in_tree_crates("sysroot", Some(target))
605                .iter()
606                .map(|c| c.name.to_string())
607                .collect()
608        } else {
609            self.crates
610        };
611
612        let out = match self.format {
613            DocumentationFormat::Html => builder.doc_out(target),
614            DocumentationFormat::Json => builder.json_doc_out(target),
615        };
616
617        t!(fs::create_dir_all(&out));
618
619        if self.format == DocumentationFormat::Html {
620            builder.ensure(SharedAssets { target: self.target });
621        }
622
623        let index_page = builder
624            .src
625            .join("src/doc/index.md")
626            .into_os_string()
627            .into_string()
628            .expect("non-utf8 paths are unsupported");
629        let mut extra_args = match self.format {
630            DocumentationFormat::Html => {
631                vec!["--markdown-css", "rust.css", "--markdown-no-toc", "--index-page", &index_page]
632            }
633            DocumentationFormat::Json => vec!["--output-format", "json"],
634        };
635
636        if !builder.config.docs_minification {
637            extra_args.push("--disable-minification");
638        }
639        // For `--index-page` and `--output-format=json`.
640        extra_args.push("-Zunstable-options");
641
642        doc_std(builder, self.format, stage, target, &out, &extra_args, &crates);
643
644        // Don't open if the format is json
645        if let DocumentationFormat::Json = self.format {
646            return;
647        }
648
649        if builder.paths.iter().any(|path| path.ends_with("library")) {
650            // For `x.py doc library --open`, open `std` by default.
651            let index = out.join("std").join("index.html");
652            builder.open_in_browser(index);
653        } else {
654            for requested_crate in crates {
655                if STD_PUBLIC_CRATES.iter().any(|&k| k == requested_crate) {
656                    let index = out.join(requested_crate).join("index.html");
657                    builder.open_in_browser(index);
658                    break;
659                }
660            }
661        }
662    }
663}
664
665/// Name of the crates that are visible to consumers of the standard library.
666/// Documentation for internal crates is handled by the rustc step, so internal crates will show
667/// up there.
668///
669/// Order here is important!
670/// Crates need to be processed starting from the leaves, otherwise rustdoc will not
671/// create correct links between crates because rustdoc depends on the
672/// existence of the output directories to know if it should be a local
673/// or remote link.
674const STD_PUBLIC_CRATES: [&str; 5] = ["core", "alloc", "std", "proc_macro", "test"];
675
676#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq, PartialOrd, Ord)]
677pub enum DocumentationFormat {
678    Html,
679    Json,
680}
681
682impl DocumentationFormat {
683    fn as_str(&self) -> &str {
684        match self {
685            DocumentationFormat::Html => "HTML",
686            DocumentationFormat::Json => "JSON",
687        }
688    }
689}
690
691/// Build the documentation for public standard library crates.
692fn doc_std(
693    builder: &Builder<'_>,
694    format: DocumentationFormat,
695    stage: u32,
696    target: TargetSelection,
697    out: &Path,
698    extra_args: &[&str],
699    requested_crates: &[String],
700) {
701    let compiler = builder.compiler(stage, builder.config.build);
702
703    let target_doc_dir_name = if format == DocumentationFormat::Json { "json-doc" } else { "doc" };
704    let target_dir = builder.stage_out(compiler, Mode::Std).join(target).join(target_doc_dir_name);
705
706    // This is directory where the compiler will place the output of the command.
707    // We will then copy the files from this directory into the final `out` directory, the specified
708    // as a function parameter.
709    let out_dir = target_dir.join(target).join("doc");
710
711    let mut cargo =
712        builder::Cargo::new(builder, compiler, Mode::Std, SourceType::InTree, target, Kind::Doc);
713
714    compile::std_cargo(builder, target, compiler.stage, &mut cargo);
715    cargo
716        .arg("--no-deps")
717        .arg("--target-dir")
718        .arg(&*target_dir.to_string_lossy())
719        .arg("-Zskip-rustdoc-fingerprint")
720        .arg("-Zrustdoc-map")
721        .rustdocflag("--extern-html-root-url")
722        .rustdocflag("std_detect=https://docs.rs/std_detect/latest/")
723        .rustdocflag("--extern-html-root-takes-precedence")
724        .rustdocflag("--resource-suffix")
725        .rustdocflag(&builder.version);
726    for arg in extra_args {
727        cargo.rustdocflag(arg);
728    }
729
730    if builder.config.library_docs_private_items {
731        cargo.rustdocflag("--document-private-items").rustdocflag("--document-hidden-items");
732    }
733
734    for krate in requested_crates {
735        if krate == "sysroot" {
736            // The sysroot crate is an implementation detail, don't include it in public docs.
737            continue;
738        }
739        cargo.arg("-p").arg(krate);
740    }
741
742    let description =
743        format!("library{} in {} format", crate_description(requested_crates), format.as_str());
744    let _guard = builder.msg_doc(compiler, description, target);
745
746    cargo.into_cmd().run(builder);
747    builder.cp_link_r(&out_dir, out);
748}
749
750#[derive(Debug, Clone, Hash, PartialEq, Eq)]
751pub struct Rustc {
752    pub stage: u32,
753    pub target: TargetSelection,
754    crates: Vec<String>,
755}
756
757impl Rustc {
758    pub(crate) fn new(stage: u32, target: TargetSelection, builder: &Builder<'_>) -> Self {
759        let crates = builder
760            .in_tree_crates("rustc-main", Some(target))
761            .into_iter()
762            .map(|krate| krate.name.to_string())
763            .collect();
764        Self { stage, target, crates }
765    }
766}
767
768impl Step for Rustc {
769    type Output = ();
770    const DEFAULT: bool = true;
771    const ONLY_HOSTS: bool = true;
772
773    fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
774        let builder = run.builder;
775        run.crate_or_deps("rustc-main")
776            .path("compiler")
777            .default_condition(builder.config.compiler_docs)
778    }
779
780    fn make_run(run: RunConfig<'_>) {
781        run.builder.ensure(Rustc {
782            stage: run.builder.top_stage,
783            target: run.target,
784            crates: run.make_run_crates(Alias::Compiler),
785        });
786    }
787
788    /// Generates compiler documentation.
789    ///
790    /// This will generate all documentation for compiler and dependencies.
791    /// Compiler documentation is distributed separately, so we make sure
792    /// we do not merge it with the other documentation from std, test and
793    /// proc_macros. This is largely just a wrapper around `cargo doc`.
794    fn run(self, builder: &Builder<'_>) {
795        let stage = self.stage;
796        let target = self.target;
797
798        // This is the intended out directory for compiler documentation.
799        let out = builder.compiler_doc_out(target);
800        t!(fs::create_dir_all(&out));
801
802        // Build the standard library, so that proc-macros can use it.
803        // (Normally, only the metadata would be necessary, but proc-macros are special since they run at compile-time.)
804        let compiler = builder.compiler(stage, builder.config.build);
805        builder.ensure(compile::Std::new(compiler, builder.config.build));
806
807        let _guard = builder.msg_sysroot_tool(
808            Kind::Doc,
809            stage,
810            format!("compiler{}", crate_description(&self.crates)),
811            compiler.host,
812            target,
813        );
814
815        // Build cargo command.
816        let mut cargo = builder::Cargo::new(
817            builder,
818            compiler,
819            Mode::Rustc,
820            SourceType::InTree,
821            target,
822            Kind::Doc,
823        );
824
825        cargo.rustdocflag("--document-private-items");
826        // Since we always pass --document-private-items, there's no need to warn about linking to private items.
827        cargo.rustdocflag("-Arustdoc::private-intra-doc-links");
828        cargo.rustdocflag("--enable-index-page");
829        cargo.rustdocflag("-Znormalize-docs");
830        cargo.rustdocflag("--show-type-layout");
831        // FIXME: `--generate-link-to-definition` tries to resolve cfged out code
832        // see https://github.com/rust-lang/rust/pull/122066#issuecomment-1983049222
833        // If there is any bug, please comment out the next line.
834        cargo.rustdocflag("--generate-link-to-definition");
835
836        compile::rustc_cargo(builder, &mut cargo, target, &compiler, &self.crates);
837        cargo.arg("-Zskip-rustdoc-fingerprint");
838
839        // Only include compiler crates, no dependencies of those, such as `libc`.
840        // Do link to dependencies on `docs.rs` however using `rustdoc-map`.
841        cargo.arg("--no-deps");
842        cargo.arg("-Zrustdoc-map");
843
844        // FIXME: `-Zrustdoc-map` does not yet correctly work for transitive dependencies,
845        // once this is no longer an issue the special case for `ena` can be removed.
846        cargo.rustdocflag("--extern-html-root-url");
847        cargo.rustdocflag("ena=https://docs.rs/ena/latest/");
848
849        let mut to_open = None;
850
851        let out_dir = builder.stage_out(compiler, Mode::Rustc).join(target).join("doc");
852        for krate in &*self.crates {
853            // Create all crate output directories first to make sure rustdoc uses
854            // relative links.
855            // FIXME: Cargo should probably do this itself.
856            let dir_name = krate.replace('-', "_");
857            t!(fs::create_dir_all(out_dir.join(&*dir_name)));
858            cargo.arg("-p").arg(krate);
859            if to_open.is_none() {
860                to_open = Some(dir_name);
861            }
862        }
863
864        // This uses a shared directory so that librustdoc documentation gets
865        // correctly built and merged with the rustc documentation.
866        //
867        // This is needed because rustdoc is built in a different directory from
868        // rustc. rustdoc needs to be able to see everything, for example when
869        // merging the search index, or generating local (relative) links.
870        symlink_dir_force(&builder.config, &out, &out_dir);
871        // Cargo puts proc macros in `target/doc` even if you pass `--target`
872        // explicitly (https://github.com/rust-lang/cargo/issues/7677).
873        let proc_macro_out_dir = builder.stage_out(compiler, Mode::Rustc).join("doc");
874        symlink_dir_force(&builder.config, &out, &proc_macro_out_dir);
875
876        cargo.into_cmd().run(builder);
877
878        if !builder.config.dry_run() {
879            // Sanity check on linked compiler crates
880            for krate in &*self.crates {
881                let dir_name = krate.replace('-', "_");
882                // Making sure the directory exists and is not empty.
883                assert!(out.join(&*dir_name).read_dir().unwrap().next().is_some());
884            }
885        }
886
887        if builder.paths.iter().any(|path| path.ends_with("compiler")) {
888            // For `x.py doc compiler --open`, open `rustc_middle` by default.
889            let index = out.join("rustc_middle").join("index.html");
890            builder.open_in_browser(index);
891        } else if let Some(krate) = to_open {
892            // Let's open the first crate documentation page:
893            let index = out.join(krate).join("index.html");
894            builder.open_in_browser(index);
895        }
896    }
897}
898
899macro_rules! tool_doc {
900    (
901        $tool: ident,
902        $path: literal,
903        $(rustc_tool = $rustc_tool:literal, )?
904        $(is_library = $is_library:expr,)?
905        $(crates = $crates:expr)?
906       ) => {
907        #[derive(Debug, Clone, Hash, PartialEq, Eq)]
908        pub struct $tool {
909            target: TargetSelection,
910        }
911
912        impl Step for $tool {
913            type Output = ();
914            const DEFAULT: bool = true;
915            const ONLY_HOSTS: bool = true;
916
917            fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
918                let builder = run.builder;
919                run.path($path).default_condition(builder.config.compiler_docs)
920            }
921
922            fn make_run(run: RunConfig<'_>) {
923                run.builder.ensure($tool { target: run.target });
924            }
925
926            /// Generates compiler documentation.
927            ///
928            /// This will generate all documentation for compiler and dependencies.
929            /// Compiler documentation is distributed separately, so we make sure
930            /// we do not merge it with the other documentation from std, test and
931            /// proc_macros. This is largely just a wrapper around `cargo doc`.
932            fn run(self, builder: &Builder<'_>) {
933                let mut source_type = SourceType::InTree;
934
935                if let Some(submodule_path) = submodule_path_of(&builder, $path) {
936                    source_type = SourceType::Submodule;
937                    builder.require_submodule(&submodule_path, None);
938                }
939
940                let stage = builder.top_stage;
941                let target = self.target;
942
943                // This is the intended out directory for compiler documentation.
944                let out = builder.compiler_doc_out(target);
945                t!(fs::create_dir_all(&out));
946
947                let compiler = builder.compiler(stage, builder.config.build);
948                builder.ensure(compile::Std::new(compiler, target));
949
950                if true $(&& $rustc_tool)? {
951                    // Build rustc docs so that we generate relative links.
952                    builder.ensure(Rustc::new(stage, target, builder));
953
954                    // Rustdoc needs the rustc sysroot available to build.
955                    // FIXME: is there a way to only ensure `check::Rustc` here? Last time I tried it failed
956                    // with strange errors, but only on a full bors test ...
957                    builder.ensure(compile::Rustc::new(compiler, target));
958                }
959
960                // Build cargo command.
961                let mut cargo = prepare_tool_cargo(
962                    builder,
963                    compiler,
964                    Mode::ToolRustc,
965                    target,
966                    Kind::Doc,
967                    $path,
968                    source_type,
969                    &[],
970                );
971
972                cargo.arg("-Zskip-rustdoc-fingerprint");
973                // Only include compiler crates, no dependencies of those, such as `libc`.
974                cargo.arg("--no-deps");
975
976                if false $(|| $is_library)? {
977                    cargo.arg("--lib");
978                }
979
980                $(for krate in $crates {
981                    cargo.arg("-p").arg(krate);
982                })?
983
984                cargo.rustdocflag("--document-private-items");
985                // Since we always pass --document-private-items, there's no need to warn about linking to private items.
986                cargo.rustdocflag("-Arustdoc::private-intra-doc-links");
987                cargo.rustdocflag("--enable-index-page");
988                cargo.rustdocflag("--show-type-layout");
989                // FIXME: `--generate-link-to-definition` tries to resolve cfged out code
990                // see https://github.com/rust-lang/rust/pull/122066#issuecomment-1983049222
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        // config.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
