| #![doc( |
| html_root_url = "https://doc.rust-lang.org/nightly/", |
| html_playground_url = "https://play.rust-lang.org/" |
| )] |
| #![feature(rustc_private)] |
| #![feature(assert_matches)] |
| #![feature(box_patterns)] |
| #![feature(file_buffered)] |
| #![feature(if_let_guard)] |
| #![feature(impl_trait_in_assoc_type)] |
| #![feature(iter_intersperse)] |
| #![feature(let_chains)] |
| #![feature(never_type)] |
| #![feature(os_str_display)] |
| #![feature(round_char_boundary)] |
| #![feature(test)] |
| #![feature(type_alias_impl_trait)] |
| #![feature(type_ascription)] |
| #![recursion_limit = "256"] |
| #![warn(rustc::internal)] |
| #![allow(clippy::collapsible_if, clippy::collapsible_else_if)] |
| #![allow(rustc::diagnostic_outside_of_impl)] |
| #![allow(rustc::untranslatable_diagnostic)] |
| |
| extern crate thin_vec; |
| |
| // N.B. these need `extern crate` even in 2018 edition |
| // because they're loaded implicitly from the sysroot. |
| // The reason they're loaded from the sysroot is because |
| // the rustdoc artifacts aren't stored in rustc's cargo target directory. |
| // So if `rustc` was specified in Cargo.toml, this would spuriously rebuild crates. |
| // |
| // Dependencies listed in Cargo.toml do not need `extern crate`. |
| |
| extern crate pulldown_cmark; |
| extern crate rustc_abi; |
| extern crate rustc_ast; |
| extern crate rustc_ast_pretty; |
| extern crate rustc_attr; |
| extern crate rustc_const_eval; |
| extern crate rustc_data_structures; |
| extern crate rustc_driver; |
| extern crate rustc_errors; |
| extern crate rustc_expand; |
| extern crate rustc_feature; |
| extern crate rustc_hir; |
| extern crate rustc_hir_analysis; |
| extern crate rustc_hir_pretty; |
| extern crate rustc_index; |
| extern crate rustc_infer; |
| extern crate rustc_interface; |
| extern crate rustc_lexer; |
| extern crate rustc_lint; |
| extern crate rustc_lint_defs; |
| extern crate rustc_log; |
| extern crate rustc_macros; |
| extern crate rustc_metadata; |
| extern crate rustc_middle; |
| extern crate rustc_parse; |
| extern crate rustc_passes; |
| extern crate rustc_resolve; |
| extern crate rustc_serialize; |
| extern crate rustc_session; |
| extern crate rustc_span; |
| extern crate rustc_target; |
| extern crate rustc_trait_selection; |
| extern crate test; |
| |
| // See docs in https://github.com/rust-lang/rust/blob/master/compiler/rustc/src/main.rs |
| // about jemalloc. |
| #[cfg(feature = "jemalloc")] |
| extern crate jemalloc_sys; |
| |
| use std::env::{self, VarError}; |
| use std::io::{self, IsTerminal}; |
| use std::process; |
| use std::sync::Arc; |
| use std::sync::atomic::AtomicBool; |
| |
| use rustc_errors::{DiagCtxtHandle, ErrorGuaranteed, FatalError}; |
| use rustc_interface::interface; |
| use rustc_middle::ty::TyCtxt; |
| use rustc_session::config::{ErrorOutputType, RustcOptGroup, make_crate_type_option}; |
| use rustc_session::{EarlyDiagCtxt, getopts}; |
| use tracing::info; |
| |
| use crate::clean::utils::DOC_RUST_LANG_ORG_CHANNEL; |
| |
| /// A macro to create a FxHashMap. |
| /// |
| /// Example: |
| /// |
| /// ```ignore(cannot-test-this-because-non-exported-macro) |
| /// let letters = map!{"a" => "b", "c" => "d"}; |
| /// ``` |
| /// |
| /// Trailing commas are allowed. |
| /// Commas between elements are required (even if the expression is a block). |
| macro_rules! map { |
| ($( $key: expr => $val: expr ),* $(,)*) => {{ |
| let mut map = ::rustc_data_structures::fx::FxIndexMap::default(); |
| $( map.insert($key, $val); )* |
| map |
| }} |
| } |
| |
| mod clean; |
| mod config; |
| mod core; |
| mod docfs; |
| mod doctest; |
| mod error; |
| mod externalfiles; |
| mod fold; |
| mod formats; |
| // used by the error-index generator, so it needs to be public |
| pub mod html; |
| mod json; |
| pub(crate) mod lint; |
| mod markdown; |
| mod passes; |
| mod scrape_examples; |
| mod theme; |
| mod visit; |
| mod visit_ast; |
| mod visit_lib; |
| |
| pub fn main() { |
| // See docs in https://github.com/rust-lang/rust/blob/master/compiler/rustc/src/main.rs |
| // about jemalloc. |
| #[cfg(feature = "jemalloc")] |
| { |
| use std::os::raw::{c_int, c_void}; |
| |
| #[used] |
| static _F1: unsafe extern "C" fn(usize, usize) -> *mut c_void = jemalloc_sys::calloc; |
| #[used] |
| static _F2: unsafe extern "C" fn(*mut *mut c_void, usize, usize) -> c_int = |
| jemalloc_sys::posix_memalign; |
| #[used] |
| static _F3: unsafe extern "C" fn(usize, usize) -> *mut c_void = jemalloc_sys::aligned_alloc; |
| #[used] |
| static _F4: unsafe extern "C" fn(usize) -> *mut c_void = jemalloc_sys::malloc; |
| #[used] |
| static _F5: unsafe extern "C" fn(*mut c_void, usize) -> *mut c_void = jemalloc_sys::realloc; |
| #[used] |
| static _F6: unsafe extern "C" fn(*mut c_void) = jemalloc_sys::free; |
| |
| #[cfg(target_os = "macos")] |
| { |
| extern "C" { |
| fn _rjem_je_zone_register(); |
| } |
| |
| #[used] |
| static _F7: unsafe extern "C" fn() = _rjem_je_zone_register; |
| } |
| } |
| |
| let mut early_dcx = EarlyDiagCtxt::new(ErrorOutputType::default()); |
| |
| let using_internal_features = rustc_driver::install_ice_hook( |
| "https://github.com/rust-lang/rust/issues/new\ |
| ?labels=C-bug%2C+I-ICE%2C+T-rustdoc&template=ice.md", |
| |_| (), |
| ); |
| |
| // When using CI artifacts with `download-rustc`, tracing is unconditionally built |
| // with `--features=static_max_level_info`, which disables almost all rustdoc logging. To avoid |
| // this, compile our own version of `tracing` that logs all levels. |
| // NOTE: this compiles both versions of tracing unconditionally, because |
| // - The compile time hit is not that bad, especially compared to rustdoc's incremental times, and |
| // - Otherwise, there's no warning that logging is being ignored when `download-rustc` is enabled |
| // NOTE: The reason this doesn't show double logging when `download-rustc = false` and |
| // `debug_logging = true` is because all rustc logging goes to its version of tracing (the one |
| // in the sysroot), and all of rustdoc's logging goes to its version (the one in Cargo.toml). |
| |
| init_logging(&early_dcx); |
| rustc_driver::init_logger(&early_dcx, rustc_log::LoggerConfig::from_env("RUSTDOC_LOG")); |
| |
| let exit_code = rustc_driver::catch_with_exit_code(|| { |
| let at_args = rustc_driver::args::raw_args(&early_dcx)?; |
| main_args(&mut early_dcx, &at_args, using_internal_features) |
| }); |
| process::exit(exit_code); |
| } |
| |
| fn init_logging(early_dcx: &EarlyDiagCtxt) { |
| let color_logs = match env::var("RUSTDOC_LOG_COLOR").as_deref() { |
| Ok("always") => true, |
| Ok("never") => false, |
| Ok("auto") | Err(VarError::NotPresent) => io::stdout().is_terminal(), |
| Ok(value) => early_dcx.early_fatal(format!( |
| "invalid log color value '{value}': expected one of always, never, or auto", |
| )), |
| Err(VarError::NotUnicode(value)) => early_dcx.early_fatal(format!( |
| "invalid log color value '{}': expected one of always, never, or auto", |
| value.to_string_lossy() |
| )), |
| }; |
| let filter = tracing_subscriber::EnvFilter::from_env("RUSTDOC_LOG"); |
| let layer = tracing_tree::HierarchicalLayer::default() |
| .with_writer(io::stderr) |
| .with_ansi(color_logs) |
| .with_targets(true) |
| .with_wraparound(10) |
| .with_verbose_exit(true) |
| .with_verbose_entry(true) |
| .with_indent_amount(2); |
| #[cfg(all(parallel_compiler, debug_assertions))] |
| let layer = layer.with_thread_ids(true).with_thread_names(true); |
| |
| use tracing_subscriber::layer::SubscriberExt; |
| let subscriber = tracing_subscriber::Registry::default().with(filter).with(layer); |
| tracing::subscriber::set_global_default(subscriber).unwrap(); |
| } |
| |
| fn opts() -> Vec<RustcOptGroup> { |
| let stable: fn(_, fn(&mut getopts::Options) -> &mut _) -> _ = RustcOptGroup::stable; |
| let unstable: fn(_, fn(&mut getopts::Options) -> &mut _) -> _ = RustcOptGroup::unstable; |
| vec![ |
| stable("h", |o| o.optflagmulti("h", "help", "show this help message")), |
| stable("V", |o| o.optflagmulti("V", "version", "print rustdoc's version")), |
| stable("v", |o| o.optflagmulti("v", "verbose", "use verbose output")), |
| stable("w", |o| o.optopt("w", "output-format", "the output type to write", "[html]")), |
| stable("output", |o| { |
| o.optopt( |
| "", |
| "output", |
| "Which directory to place the output. \ |
| This option is deprecated, use --out-dir instead.", |
| "PATH", |
| ) |
| }), |
| stable("o", |o| o.optopt("o", "out-dir", "which directory to place the output", "PATH")), |
| stable("crate-name", |o| { |
| o.optopt("", "crate-name", "specify the name of this crate", "NAME") |
| }), |
| make_crate_type_option(), |
| stable("L", |o| { |
| o.optmulti("L", "library-path", "directory to add to crate search path", "DIR") |
| }), |
| stable("cfg", |o| o.optmulti("", "cfg", "pass a --cfg to rustc", "")), |
| stable("check-cfg", |o| o.optmulti("", "check-cfg", "pass a --check-cfg to rustc", "")), |
| stable("extern", |o| o.optmulti("", "extern", "pass an --extern to rustc", "NAME[=PATH]")), |
| unstable("extern-html-root-url", |o| { |
| o.optmulti( |
| "", |
| "extern-html-root-url", |
| "base URL to use for dependencies; for example, \ |
| \"std=/doc\" links std::vec::Vec to /doc/std/vec/struct.Vec.html", |
| "NAME=URL", |
| ) |
| }), |
| unstable("extern-html-root-takes-precedence", |o| { |
| o.optflagmulti( |
| "", |
| "extern-html-root-takes-precedence", |
| "give precedence to `--extern-html-root-url`, not `html_root_url`", |
| ) |
| }), |
| stable("C", |o| { |
| o.optmulti("C", "codegen", "pass a codegen option to rustc", "OPT[=VALUE]") |
| }), |
| stable("document-private-items", |o| { |
| o.optflagmulti("", "document-private-items", "document private items") |
| }), |
| unstable("document-hidden-items", |o| { |
| o.optflagmulti("", "document-hidden-items", "document items that have doc(hidden)") |
| }), |
| stable("test", |o| o.optflagmulti("", "test", "run code examples as tests")), |
| stable("test-args", |o| { |
| o.optmulti("", "test-args", "arguments to pass to the test runner", "ARGS") |
| }), |
| stable("test-run-directory", |o| { |
| o.optopt( |
| "", |
| "test-run-directory", |
| "The working directory in which to run tests", |
| "PATH", |
| ) |
| }), |
| stable("target", |o| o.optopt("", "target", "target triple to document", "TRIPLE")), |
| stable("markdown-css", |o| { |
| o.optmulti( |
| "", |
| "markdown-css", |
| "CSS files to include via <link> in a rendered Markdown file", |
| "FILES", |
| ) |
| }), |
| stable("html-in-header", |o| { |
| o.optmulti( |
| "", |
| "html-in-header", |
| "files to include inline in the <head> section of a rendered Markdown file \ |
| or generated documentation", |
| "FILES", |
| ) |
| }), |
| stable("html-before-content", |o| { |
| o.optmulti( |
| "", |
| "html-before-content", |
| "files to include inline between <body> and the content of a rendered \ |
| Markdown file or generated documentation", |
| "FILES", |
| ) |
| }), |
| stable("html-after-content", |o| { |
| o.optmulti( |
| "", |
| "html-after-content", |
| "files to include inline between the content and </body> of a rendered \ |
| Markdown file or generated documentation", |
| "FILES", |
| ) |
| }), |
| unstable("markdown-before-content", |o| { |
| o.optmulti( |
| "", |
| "markdown-before-content", |
| "files to include inline between <body> and the content of a rendered \ |
| Markdown file or generated documentation", |
| "FILES", |
| ) |
| }), |
| unstable("markdown-after-content", |o| { |
| o.optmulti( |
| "", |
| "markdown-after-content", |
| "files to include inline between the content and </body> of a rendered \ |
| Markdown file or generated documentation", |
| "FILES", |
| ) |
| }), |
| stable("markdown-playground-url", |o| { |
| o.optopt("", "markdown-playground-url", "URL to send code snippets to", "URL") |
| }), |
| stable("markdown-no-toc", |o| { |
| o.optflagmulti("", "markdown-no-toc", "don't include table of contents") |
| }), |
| stable("e", |o| { |
| o.optopt( |
| "e", |
| "extend-css", |
| "To add some CSS rules with a given file to generate doc with your \ |
| own theme. However, your theme might break if the rustdoc's generated HTML \ |
| changes, so be careful!", |
| "PATH", |
| ) |
| }), |
| unstable("Z", |o| { |
| o.optmulti("Z", "", "unstable / perma-unstable options (only on nightly build)", "FLAG") |
| }), |
| stable("sysroot", |o| o.optopt("", "sysroot", "Override the system root", "PATH")), |
| unstable("playground-url", |o| { |
| o.optopt( |
| "", |
| "playground-url", |
| "URL to send code snippets to, may be reset by --markdown-playground-url \ |
| or `#![doc(html_playground_url=...)]`", |
| "URL", |
| ) |
| }), |
| unstable("display-doctest-warnings", |o| { |
| o.optflagmulti( |
| "", |
| "display-doctest-warnings", |
| "show warnings that originate in doctests", |
| ) |
| }), |
| stable("crate-version", |o| { |
| o.optopt("", "crate-version", "crate version to print into documentation", "VERSION") |
| }), |
| unstable("sort-modules-by-appearance", |o| { |
| o.optflagmulti( |
| "", |
| "sort-modules-by-appearance", |
| "sort modules by where they appear in the program, rather than alphabetically", |
| ) |
| }), |
| stable("default-theme", |o| { |
| o.optopt( |
| "", |
| "default-theme", |
| "Set the default theme. THEME should be the theme name, generally lowercase. \ |
| If an unknown default theme is specified, the builtin default is used. \ |
| The set of themes, and the rustdoc built-in default, are not stable.", |
| "THEME", |
| ) |
| }), |
| unstable("default-setting", |o| { |
| o.optmulti( |
| "", |
| "default-setting", |
| "Default value for a rustdoc setting (used when \"rustdoc-SETTING\" is absent \ |
| from web browser Local Storage). If VALUE is not supplied, \"true\" is used. \ |
| Supported SETTINGs and VALUEs are not documented and not stable.", |
| "SETTING[=VALUE]", |
| ) |
| }), |
| stable("theme", |o| { |
| o.optmulti( |
| "", |
| "theme", |
| "additional themes which will be added to the generated docs", |
| "FILES", |
| ) |
| }), |
| stable("check-theme", |o| { |
| o.optmulti("", "check-theme", "check if given theme is valid", "FILES") |
| }), |
| unstable("resource-suffix", |o| { |
| o.optopt( |
| "", |
| "resource-suffix", |
| "suffix to add to CSS and JavaScript files, e.g., \"search-index.js\" will \ |
| become \"search-index-suffix.js\"", |
| "PATH", |
| ) |
| }), |
| stable("edition", |o| { |
| o.optopt( |
| "", |
| "edition", |
| "edition to use when compiling rust code (default: 2015)", |
| "EDITION", |
| ) |
| }), |
| stable("color", |o| { |
| o.optopt( |
| "", |
| "color", |
| "Configure coloring of output: |
| auto = colorize, if output goes to a tty (default); |
| always = always colorize output; |
| never = never colorize output", |
| "auto|always|never", |
| ) |
| }), |
| stable("error-format", |o| { |
| o.optopt( |
| "", |
| "error-format", |
| "How errors and other messages are produced", |
| "human|json|short", |
| ) |
| }), |
| stable("diagnostic-width", |o| { |
| o.optopt( |
| "", |
| "diagnostic-width", |
| "Provide width of the output for truncated error messages", |
| "WIDTH", |
| ) |
| }), |
| stable("json", |o| { |
| o.optopt("", "json", "Configure the structure of JSON diagnostics", "CONFIG") |
| }), |
| stable("allow", |o| o.optmulti("A", "allow", "Set lint allowed", "LINT")), |
| stable("warn", |o| o.optmulti("W", "warn", "Set lint warnings", "LINT")), |
| stable("force-warn", |o| o.optmulti("", "force-warn", "Set lint force-warn", "LINT")), |
| stable("deny", |o| o.optmulti("D", "deny", "Set lint denied", "LINT")), |
| stable("forbid", |o| o.optmulti("F", "forbid", "Set lint forbidden", "LINT")), |
| stable("cap-lints", |o| { |
| o.optmulti( |
| "", |
| "cap-lints", |
| "Set the most restrictive lint level. \ |
| More restrictive lints are capped at this \ |
| level. By default, it is at `forbid` level.", |
| "LEVEL", |
| ) |
| }), |
| unstable("index-page", |o| { |
| o.optopt("", "index-page", "Markdown file to be used as index page", "PATH") |
| }), |
| unstable("enable-index-page", |o| { |
| o.optflagmulti("", "enable-index-page", "To enable generation of the index page") |
| }), |
| unstable("static-root-path", |o| { |
| o.optopt( |
| "", |
| "static-root-path", |
| "Path string to force loading static files from in output pages. \ |
| If not set, uses combinations of '../' to reach the documentation root.", |
| "PATH", |
| ) |
| }), |
| unstable("persist-doctests", |o| { |
| o.optopt( |
| "", |
| "persist-doctests", |
| "Directory to persist doctest executables into", |
| "PATH", |
| ) |
| }), |
| unstable("show-coverage", |o| { |
| o.optflagmulti( |
| "", |
| "show-coverage", |
| "calculate percentage of public items with documentation", |
| ) |
| }), |
| unstable("enable-per-target-ignores", |o| { |
| o.optflagmulti( |
| "", |
| "enable-per-target-ignores", |
| "parse ignore-foo for ignoring doctests on a per-target basis", |
| ) |
| }), |
| unstable("runtool", |o| { |
| o.optopt( |
| "", |
| "runtool", |
| "", |
| "The tool to run tests with when building for a different target than host", |
| ) |
| }), |
| unstable("runtool-arg", |o| { |
| o.optmulti( |
| "", |
| "runtool-arg", |
| "", |
| "One (of possibly many) arguments to pass to the runtool", |
| ) |
| }), |
| unstable("test-builder", |o| { |
| o.optopt("", "test-builder", "The rustc-like binary to use as the test builder", "PATH") |
| }), |
| unstable("test-builder-wrapper", |o| { |
| o.optmulti( |
| "", |
| "test-builder-wrapper", |
| "Wrapper program to pass test-builder and arguments", |
| "PATH", |
| ) |
| }), |
| unstable("check", |o| o.optflagmulti("", "check", "Run rustdoc checks")), |
| unstable("generate-redirect-map", |o| { |
| o.optflagmulti( |
| "", |
| "generate-redirect-map", |
| "Generate JSON file at the top level instead of generating HTML redirection files", |
| ) |
| }), |
| unstable("emit", |o| { |
| o.optmulti( |
| "", |
| "emit", |
| "Comma separated list of types of output for rustdoc to emit", |
| "[unversioned-shared-resources,toolchain-shared-resources,invocation-specific]", |
| ) |
| }), |
| unstable("no-run", |o| { |
| o.optflagmulti("", "no-run", "Compile doctests without running them") |
| }), |
| unstable("remap-path-prefix", |o| { |
| o.optmulti( |
| "", |
| "remap-path-prefix", |
| "Remap source names in compiler messages", |
| "FROM=TO", |
| ) |
| }), |
| unstable("show-type-layout", |o| { |
| o.optflagmulti("", "show-type-layout", "Include the memory layout of types in the docs") |
| }), |
| unstable("nocapture", |o| { |
| o.optflag("", "nocapture", "Don't capture stdout and stderr of tests") |
| }), |
| unstable("generate-link-to-definition", |o| { |
| o.optflag( |
| "", |
| "generate-link-to-definition", |
| "Make the identifiers in the HTML source code pages navigable", |
| ) |
| }), |
| unstable("scrape-examples-output-path", |o| { |
| o.optopt( |
| "", |
| "scrape-examples-output-path", |
| "", |
| "collect function call information and output at the given path", |
| ) |
| }), |
| unstable("scrape-examples-target-crate", |o| { |
| o.optmulti( |
| "", |
| "scrape-examples-target-crate", |
| "", |
| "collect function call information for functions from the target crate", |
| ) |
| }), |
| unstable("scrape-tests", |o| { |
| o.optflag("", "scrape-tests", "Include test code when scraping examples") |
| }), |
| unstable("with-examples", |o| { |
| o.optmulti( |
| "", |
| "with-examples", |
| "", |
| "path to function call information (for displaying examples in the documentation)", |
| ) |
| }), |
| unstable("merge", |o| { |
| o.optopt( |
| "", |
| "merge", |
| "Controls how rustdoc handles files from previously documented crates in the doc root |
| none = Do not write cross-crate information to the --out-dir |
| shared = Append current crate's info to files found in the --out-dir |
| finalize = Write current crate's info and --include-parts-dir info to the --out-dir, overwriting conflicting files", |
| "none|shared|finalize", |
| ) |
| }), |
| unstable("parts-out-dir", |o| { |
| o.optopt( |
| "", |
| "parts-out-dir", |
| "Writes trait implementations and other info for the current crate to provided path. Only use with --merge=none", |
| "path/to/doc.parts/<crate-name>", |
| ) |
| }), |
| unstable("include-parts-dir", |o| { |
| o.optmulti( |
| "", |
| "include-parts-dir", |
| "Includes trait implementations and other crate info from provided path. Only use with --merge=finalize", |
| "path/to/doc.parts/<crate-name>", |
| ) |
| }), |
| // deprecated / removed options |
| unstable("disable-minification", |o| o.optflagmulti("", "disable-minification", "removed")), |
| stable("plugin-path", |o| { |
| o.optmulti( |
| "", |
| "plugin-path", |
| "removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \ |
| for more information", |
| "DIR", |
| ) |
| }), |
| stable("passes", |o| { |
| o.optmulti( |
| "", |
| "passes", |
| "removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \ |
| for more information", |
| "PASSES", |
| ) |
| }), |
| stable("plugins", |o| { |
| o.optmulti( |
| "", |
| "plugins", |
| "removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \ |
| for more information", |
| "PLUGINS", |
| ) |
| }), |
| stable("no-default", |o| { |
| o.optflagmulti( |
| "", |
| "no-defaults", |
| "removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \ |
| for more information", |
| ) |
| }), |
| stable("r", |o| { |
| o.optopt( |
| "r", |
| "input-format", |
| "removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \ |
| for more information", |
| "[rust]", |
| ) |
| }), |
| unstable("html-no-source", |o| { |
| o.optflag("", "html-no-source", "Disable HTML source code pages generation") |
| }), |
| ] |
| } |
| |
| fn usage(argv0: &str) { |
| let mut options = getopts::Options::new(); |
| for option in opts() { |
| (option.apply)(&mut options); |
| } |
| println!("{}", options.usage(&format!("{argv0} [options] <input>"))); |
| println!(" @path Read newline separated options from `path`\n"); |
| println!( |
| "More information available at {DOC_RUST_LANG_ORG_CHANNEL}/rustdoc/what-is-rustdoc.html", |
| ); |
| } |
| |
| /// A result type used by several functions under `main()`. |
| type MainResult = Result<(), ErrorGuaranteed>; |
| |
| pub(crate) fn wrap_return(dcx: DiagCtxtHandle<'_>, res: Result<(), String>) -> MainResult { |
| match res { |
| Ok(()) => dcx.has_errors().map_or(Ok(()), Err), |
| Err(err) => Err(dcx.err(err)), |
| } |
| } |
| |
| fn run_renderer<'tcx, T: formats::FormatRenderer<'tcx>>( |
| krate: clean::Crate, |
| renderopts: config::RenderOptions, |
| cache: formats::cache::Cache, |
| tcx: TyCtxt<'tcx>, |
| ) -> MainResult { |
| match formats::run_format::<T>(krate, renderopts, cache, tcx) { |
| Ok(_) => tcx.dcx().has_errors().map_or(Ok(()), Err), |
| Err(e) => { |
| let mut msg = |
| tcx.dcx().struct_err(format!("couldn't generate documentation: {}", e.error)); |
| let file = e.file.display().to_string(); |
| if !file.is_empty() { |
| msg.note(format!("failed to create or modify \"{file}\"")); |
| } |
| Err(msg.emit()) |
| } |
| } |
| } |
| |
| /// Renders and writes cross-crate info files, like the search index. This function exists so that |
| /// we can run rustdoc without a crate root in the `--merge=finalize` mode. Cross-crate info files |
| /// discovered via `--include-parts-dir` are combined and written to the doc root. |
| fn run_merge_finalize(opt: config::RenderOptions) -> Result<(), error::Error> { |
| assert!( |
| opt.should_merge.write_rendered_cci, |
| "config.rs only allows us to return InputMode::NoInputMergeFinalize if --merge=finalize" |
| ); |
| assert!( |
| !opt.should_merge.read_rendered_cci, |
| "config.rs only allows us to return InputMode::NoInputMergeFinalize if --merge=finalize" |
| ); |
| let crates = html::render::CrateInfo::read_many(&opt.include_parts_dir)?; |
| let include_sources = !opt.html_no_source; |
| html::render::write_not_crate_specific( |
| &crates, |
| &opt.output, |
| &opt, |
| &opt.themes, |
| opt.extension_css.as_deref(), |
| &opt.resource_suffix, |
| include_sources, |
| )?; |
| Ok(()) |
| } |
| |
| fn main_args( |
| early_dcx: &mut EarlyDiagCtxt, |
| at_args: &[String], |
| using_internal_features: Arc<AtomicBool>, |
| ) -> MainResult { |
| // Throw away the first argument, the name of the binary. |
| // In case of at_args being empty, as might be the case by |
| // passing empty argument array to execve under some platforms, |
| // just use an empty slice. |
| // |
| // This situation was possible before due to arg_expand_all being |
| // called before removing the argument, enabling a crash by calling |
| // the compiler with @empty_file as argv[0] and no more arguments. |
| let at_args = at_args.get(1..).unwrap_or_default(); |
| |
| let args = rustc_driver::args::arg_expand_all(early_dcx, at_args)?; |
| |
| let mut options = getopts::Options::new(); |
| for option in opts() { |
| (option.apply)(&mut options); |
| } |
| let matches = match options.parse(&args) { |
| Ok(m) => m, |
| Err(err) => { |
| early_dcx.early_fatal(err.to_string()); |
| } |
| }; |
| |
| // Note that we discard any distinction between different non-zero exit |
| // codes from `from_matches` here. |
| let (input, options, render_options) = |
| match config::Options::from_matches(early_dcx, &matches, args) { |
| Some(opts) => opts, |
| None => return Ok(()), |
| }; |
| |
| let dcx = |
| core::new_dcx(options.error_format, None, options.diagnostic_width, &options.unstable_opts); |
| let dcx = dcx.handle(); |
| |
| let input = match input { |
| config::InputMode::HasFile(input) => input, |
| config::InputMode::NoInputMergeFinalize => { |
| return wrap_return( |
| dcx, |
| run_merge_finalize(render_options) |
| .map_err(|e| format!("could not write merged cross-crate info: {e}")), |
| ); |
| } |
| }; |
| |
| match (options.should_test, config::markdown_input(&input)) { |
| (true, Some(_)) => return wrap_return(dcx, doctest::test_markdown(&input, options)), |
| (true, None) => return doctest::run(dcx, input, options), |
| (false, Some(md_input)) => { |
| let md_input = md_input.to_owned(); |
| let edition = options.edition; |
| let config = |
| core::create_config(input, options, &render_options, using_internal_features); |
| |
| // `markdown::render` can invoke `doctest::make_test`, which |
| // requires session globals and a thread pool, so we use |
| // `run_compiler`. |
| return wrap_return( |
| dcx, |
| interface::run_compiler(config, |_compiler| { |
| markdown::render(&md_input, render_options, edition) |
| }), |
| ); |
| } |
| (false, None) => {} |
| } |
| |
| // need to move these items separately because we lose them by the time the closure is called, |
| // but we can't create the dcx ahead of time because it's not Send |
| let show_coverage = options.show_coverage; |
| let run_check = options.run_check; |
| |
| // First, parse the crate and extract all relevant information. |
| info!("starting to run rustc"); |
| |
| // Interpret the input file as a rust source file, passing it through the |
| // compiler all the way through the analysis passes. The rustdoc output is |
| // then generated from the cleaned AST of the crate. This runs all the |
| // plug/cleaning passes. |
| let crate_version = options.crate_version.clone(); |
| |
| let output_format = options.output_format; |
| let scrape_examples_options = options.scrape_examples_options.clone(); |
| let bin_crate = options.bin_crate; |
| |
| let config = core::create_config(input, options, &render_options, using_internal_features); |
| |
| interface::run_compiler(config, |compiler| { |
| let sess = &compiler.sess; |
| |
| if sess.opts.describe_lints { |
| rustc_driver::describe_lints(sess); |
| return Ok(()); |
| } |
| |
| compiler.enter(|queries| { |
| let Ok(mut gcx) = queries.global_ctxt() else { FatalError.raise() }; |
| if sess.dcx().has_errors().is_some() { |
| sess.dcx().fatal("Compilation failed, aborting rustdoc"); |
| } |
| |
| gcx.enter(|tcx| { |
| let (krate, render_opts, mut cache) = sess.time("run_global_ctxt", || { |
| core::run_global_ctxt(tcx, show_coverage, render_options, output_format) |
| })?; |
| info!("finished with rustc"); |
| |
| if let Some(options) = scrape_examples_options { |
| return scrape_examples::run( |
| krate, |
| render_opts, |
| cache, |
| tcx, |
| options, |
| bin_crate, |
| ); |
| } |
| |
| cache.crate_version = crate_version; |
| |
| if show_coverage { |
| // if we ran coverage, bail early, we don't need to also generate docs at this point |
| // (also we didn't load in any of the useful passes) |
| return Ok(()); |
| } else if run_check { |
| // Since we're in "check" mode, no need to generate anything beyond this point. |
| return Ok(()); |
| } |
| |
| info!("going to format"); |
| match output_format { |
| config::OutputFormat::Html => sess.time("render_html", || { |
| run_renderer::<html::render::Context<'_>>(krate, render_opts, cache, tcx) |
| }), |
| config::OutputFormat::Json => sess.time("render_json", || { |
| run_renderer::<json::JsonRenderer<'_>>(krate, render_opts, cache, tcx) |
| }), |
| } |
| }) |
| }) |
| }) |
| } |
