src/librustdoc/lib.rs

   1 #![doc(
   2     html_root_url = "https://doc.rust-lang.org/nightly/",
   3     html_playground_url = "https://play.rust-lang.org/"
   4 )]
   5 #![feature(rustc_private)]
   6 #![feature(box_patterns)]
   7 #![feature(box_syntax)]
   8 #![feature(in_band_lifetimes)]
   9 #![feature(nll)]
  10 #![feature(test)]
  11 #![feature(vec_remove_item)]
  12 #![feature(ptr_offset_from)]
  13 #![feature(crate_visibility_modifier)]
  14 #![feature(never_type)]
  15 #![recursion_limit = "256"]
  16
  17 extern crate env_logger;
  18 extern crate getopts;
  19 extern crate rustc;
  20 extern crate rustc_ast_pretty;
  21 extern crate rustc_attr;
  22 extern crate rustc_data_structures;
  23 extern crate rustc_driver;
  24 extern crate rustc_errors;
  25 extern crate rustc_expand;
  26 extern crate rustc_feature;
  27 extern crate rustc_hir;
  28 extern crate rustc_index;
  29 extern crate rustc_interface;
  30 extern crate rustc_lexer;
  31 extern crate rustc_lint;
  32 extern crate rustc_metadata;
  33 extern crate rustc_mir;
  34 extern crate rustc_parse;
  35 extern crate rustc_resolve;
  36 extern crate rustc_session;
  37 extern crate rustc_span as rustc_span;
  38 extern crate rustc_target;
  39 extern crate rustc_typeck;
  40 extern crate syntax;
  41 extern crate test as testing;
  42 #[macro_use]
  43 extern crate log;
  44
  45 use std::default::Default;
  46 use std::env;
  47 use std::panic;
  48 use std::process;
  49
  50 use rustc::session::config::{make_crate_type_option, ErrorOutputType, RustcOptGroup};
  51 use rustc::session::{early_error, early_warn};
  52
  53 #[macro_use]
  54 mod externalfiles;
  55
  56 mod clean;
  57 mod config;
  58 mod core;
  59 mod docfs;
  60 mod doctree;
  61 mod fold;
  62 pub mod html {
  63     crate mod escape;
  64     crate mod format;
  65     crate mod highlight;
  66     crate mod item_type;
  67     crate mod layout;
  68     pub mod markdown;
  69     crate mod render;
  70     crate mod sources;
  71     crate mod static_files;
  72     crate mod toc;
  73 }
  74 mod markdown;
  75 mod passes;
  76 mod test;
  77 mod theme;
  78 mod visit_ast;
  79 mod visit_lib;
  80
  81 struct Output {
  82     krate: clean::Crate,
  83     renderinfo: html::render::RenderInfo,
  84     renderopts: config::RenderOptions,
  85 }
  86
  87 pub fn main() {
  88     let thread_stack_size: usize = if cfg!(target_os = "haiku") {
  89         16_000_000 // 16MB on Haiku
  90     } else {
  91         32_000_000 // 32MB on other platforms
  92     };
  93     rustc_driver::set_sigpipe_handler();
  94     env_logger::init_from_env("RUSTDOC_LOG");
  95     let res = std::thread::Builder::new()
  96         .stack_size(thread_stack_size)
  97         .spawn(move || get_args().map(|args| main_args(&args)).unwrap_or(1))
  98         .unwrap()
  99         .join()
 100         .unwrap_or(rustc_driver::EXIT_FAILURE);
 101     process::exit(res);
 102 }
 103
 104 fn get_args() -> Option<Vec<String>> {
 105     env::args_os()
 106         .enumerate()
 107         .map(|(i, arg)| {
 108             arg.into_string()
 109                 .map_err(|arg| {
 110                     early_warn(
 111                         ErrorOutputType::default(),
 112                         &format!("Argument {} is not valid Unicode: {:?}", i, arg),
 113                     );
 114                 })
 115                 .ok()
 116         })
 117         .collect()
 118 }
 119
 120 fn stable<F>(name: &'static str, f: F) -> RustcOptGroup
 121 where
 122     F: Fn(&mut getopts::Options) -> &mut getopts::Options + 'static,
 123 {
 124     RustcOptGroup::stable(name, f)
 125 }
 126
 127 fn unstable<F>(name: &'static str, f: F) -> RustcOptGroup
 128 where
 129     F: Fn(&mut getopts::Options) -> &mut getopts::Options + 'static,
 130 {
 131     RustcOptGroup::unstable(name, f)
 132 }
 133
 134 fn opts() -> Vec<RustcOptGroup> {
 135     vec![
 136         stable("h", |o| o.optflag("h", "help", "show this help message")),
 137         stable("V", |o| o.optflag("V", "version", "print rustdoc's version")),
 138         stable("v", |o| o.optflag("v", "verbose", "use verbose output")),
 139         stable("r", |o| {
 140             o.optopt("r", "input-format", "the input type of the specified file", "[rust]")
 141         }),
 142         stable("w", |o| o.optopt("w", "output-format", "the output type to write", "[html]")),
 143         stable("o", |o| o.optopt("o", "output", "where to place the output", "PATH")),
 144         stable("crate-name", |o| {
 145             o.optopt("", "crate-name", "specify the name of this crate", "NAME")
 146         }),
 147         make_crate_type_option(),
 148         stable("L", |o| {
 149             o.optmulti("L", "library-path", "directory to add to crate search path", "DIR")
 150         }),
 151         stable("cfg", |o| o.optmulti("", "cfg", "pass a --cfg to rustc", "")),
 152         stable("extern", |o| o.optmulti("", "extern", "pass an --extern to rustc", "NAME[=PATH]")),
 153         unstable("extern-html-root-url", |o| {
 154             o.optmulti("", "extern-html-root-url", "base URL to use for dependencies", "NAME=URL")
 155         }),
 156         stable("plugin-path", |o| o.optmulti("", "plugin-path", "removed", "DIR")),
 157         stable("C", |o| {
 158             o.optmulti("C", "codegen", "pass a codegen option to rustc", "OPT[=VALUE]")
 159         }),
 160         stable("passes", |o| {
 161             o.optmulti(
 162                 "",
 163                 "passes",
 164                 "list of passes to also run, you might want \
 165                         to pass it multiple times; a value of `list` \
 166                         will print available passes",
 167                 "PASSES",
 168             )
 169         }),
 170         stable("plugins", |o| o.optmulti("", "plugins", "removed", "PLUGINS")),
 171         stable("no-default", |o| o.optflag("", "no-defaults", "don't run the default passes")),
 172         stable("document-private-items", |o| {
 173             o.optflag("", "document-private-items", "document private items")
 174         }),
 175         unstable("document-hidden-items", |o| {
 176             o.optflag("", "document-hidden-items", "document items that have doc(hidden)")
 177         }),
 178         stable("test", |o| o.optflag("", "test", "run code examples as tests")),
 179         stable("test-args", |o| {
 180             o.optmulti("", "test-args", "arguments to pass to the test runner", "ARGS")
 181         }),
 182         stable("target", |o| o.optopt("", "target", "target triple to document", "TRIPLE")),
 183         stable("markdown-css", |o| {
 184             o.optmulti(
 185                 "",
 186                 "markdown-css",
 187                 "CSS files to include via <link> in a rendered Markdown file",
 188                 "FILES",
 189             )
 190         }),
 191         stable("html-in-header", |o| {
 192             o.optmulti(
 193                 "",
 194                 "html-in-header",
 195                 "files to include inline in the <head> section of a rendered Markdown file \
 196                         or generated documentation",
 197                 "FILES",
 198             )
 199         }),
 200         stable("html-before-content", |o| {
 201             o.optmulti(
 202                 "",
 203                 "html-before-content",
 204                 "files to include inline between <body> and the content of a rendered \
 205                         Markdown file or generated documentation",
 206                 "FILES",
 207             )
 208         }),
 209         stable("html-after-content", |o| {
 210             o.optmulti(
 211                 "",
 212                 "html-after-content",
 213                 "files to include inline between the content and </body> of a rendered \
 214                         Markdown file or generated documentation",
 215                 "FILES",
 216             )
 217         }),
 218         unstable("markdown-before-content", |o| {
 219             o.optmulti(
 220                 "",
 221                 "markdown-before-content",
 222                 "files to include inline between <body> and the content of a rendered \
 223                         Markdown file or generated documentation",
 224                 "FILES",
 225             )
 226         }),
 227         unstable("markdown-after-content", |o| {
 228             o.optmulti(
 229                 "",
 230                 "markdown-after-content",
 231                 "files to include inline between the content and </body> of a rendered \
 232                         Markdown file or generated documentation",
 233                 "FILES",
 234             )
 235         }),
 236         stable("markdown-playground-url", |o| {
 237             o.optopt("", "markdown-playground-url", "URL to send code snippets to", "URL")
 238         }),
 239         stable("markdown-no-toc", |o| {
 240             o.optflag("", "markdown-no-toc", "don't include table of contents")
 241         }),
 242         stable("e", |o| {
 243             o.optopt(
 244                 "e",
 245                 "extend-css",
 246                 "To add some CSS rules with a given file to generate doc with your \
 247                       own theme. However, your theme might break if the rustdoc's generated HTML \
 248                       changes, so be careful!",
 249                 "PATH",
 250             )
 251         }),
 252         unstable("Z", |o| {
 253             o.optmulti("Z", "", "internal and debugging options (only on nightly build)", "FLAG")
 254         }),
 255         stable("sysroot", |o| o.optopt("", "sysroot", "Override the system root", "PATH")),
 256         unstable("playground-url", |o| {
 257             o.optopt(
 258                 "",
 259                 "playground-url",
 260                 "URL to send code snippets to, may be reset by --markdown-playground-url \
 261                       or `#![doc(html_playground_url=...)]`",
 262                 "URL",
 263             )
 264         }),
 265         unstable("display-warnings", |o| {
 266             o.optflag("", "display-warnings", "to print code warnings when testing doc")
 267         }),
 268         unstable("crate-version", |o| {
 269             o.optopt("", "crate-version", "crate version to print into documentation", "VERSION")
 270         }),
 271         unstable("sort-modules-by-appearance", |o| {
 272             o.optflag(
 273                 "",
 274                 "sort-modules-by-appearance",
 275                 "sort modules by where they appear in the \
 276                                                          program, rather than alphabetically",
 277             )
 278         }),
 279         stable("theme", |o| {
 280             o.optmulti(
 281                 "",
 282                 "theme",
 283                 "additional themes which will be added to the generated docs",
 284                 "FILES",
 285             )
 286         }),
 287         stable("check-theme", |o| {
 288             o.optmulti("", "check-theme", "check if given theme is valid", "FILES")
 289         }),
 290         unstable("resource-suffix", |o| {
 291             o.optopt(
 292                 "",
 293                 "resource-suffix",
 294                 "suffix to add to CSS and JavaScript files, e.g., \"light.css\" will become \
 295                       \"light-suffix.css\"",
 296                 "PATH",
 297             )
 298         }),
 299         stable("edition", |o| {
 300             o.optopt(
 301                 "",
 302                 "edition",
 303                 "edition to use when compiling rust code (default: 2015)",
 304                 "EDITION",
 305             )
 306         }),
 307         stable("color", |o| {
 308             o.optopt(
 309                 "",
 310                 "color",
 311                 "Configure coloring of output:
 312                                           auto   = colorize, if output goes to a tty (default);
 313                                           always = always colorize output;
 314                                           never  = never colorize output",
 315                 "auto|always|never",
 316             )
 317         }),
 318         stable("error-format", |o| {
 319             o.optopt(
 320                 "",
 321                 "error-format",
 322                 "How errors and other messages are produced",
 323                 "human|json|short",
 324             )
 325         }),
 326         stable("json", |o| {
 327             o.optopt("", "json", "Configure the structure of JSON diagnostics", "CONFIG")
 328         }),
 329         unstable("disable-minification", |o| {
 330             o.optflag("", "disable-minification", "Disable minification applied on JS files")
 331         }),
 332         stable("warn", |o| o.optmulti("W", "warn", "Set lint warnings", "OPT")),
 333         stable("allow", |o| o.optmulti("A", "allow", "Set lint allowed", "OPT")),
 334         stable("deny", |o| o.optmulti("D", "deny", "Set lint denied", "OPT")),
 335         stable("forbid", |o| o.optmulti("F", "forbid", "Set lint forbidden", "OPT")),
 336         stable("cap-lints", |o| {
 337             o.optmulti(
 338                 "",
 339                 "cap-lints",
 340                 "Set the most restrictive lint level. \
 341                  More restrictive lints are capped at this \
 342                  level. By default, it is at `forbid` level.",
 343                 "LEVEL",
 344             )
 345         }),
 346         unstable("index-page", |o| {
 347             o.optopt("", "index-page", "Markdown file to be used as index page", "PATH")
 348         }),
 349         unstable("enable-index-page", |o| {
 350             o.optflag("", "enable-index-page", "To enable generation of the index page")
 351         }),
 352         unstable("static-root-path", |o| {
 353             o.optopt(
 354                 "",
 355                 "static-root-path",
 356                 "Path string to force loading static files from in output pages. \
 357                       If not set, uses combinations of '../' to reach the documentation root.",
 358                 "PATH",
 359             )
 360         }),
 361         unstable("disable-per-crate-search", |o| {
 362             o.optflag(
 363                 "",
 364                 "disable-per-crate-search",
 365                 "disables generating the crate selector on the search box",
 366             )
 367         }),
 368         unstable("persist-doctests", |o| {
 369             o.optopt(
 370                 "",
 371                 "persist-doctests",
 372                 "Directory to persist doctest executables into",
 373                 "PATH",
 374             )
 375         }),
 376         unstable("generate-redirect-pages", |o| {
 377             o.optflag(
 378                 "",
 379                 "generate-redirect-pages",
 380                 "Generate extra pages to support legacy URLs and tool links",
 381             )
 382         }),
 383         unstable("show-coverage", |o| {
 384             o.optflag(
 385                 "",
 386                 "show-coverage",
 387                 "calculate percentage of public items with documentation",
 388             )
 389         }),
 390         unstable("enable-per-target-ignores", |o| {
 391             o.optflag(
 392                 "",
 393                 "enable-per-target-ignores",
 394                 "parse ignore-foo for ignoring doctests on a per-target basis",
 395             )
 396         }),
 397         unstable("runtool", |o| {
 398             o.optopt(
 399                 "",
 400                 "runtool",
 401                 "",
 402                 "The tool to run tests with when building for a different target than host",
 403             )
 404         }),
 405         unstable("runtool-arg", |o| {
 406             o.optmulti(
 407                 "",
 408                 "runtool-arg",
 409                 "",
 410                 "One (of possibly many) arguments to pass to the runtool",
 411             )
 412         }),
 413         unstable("test-builder", |o| {
 414             o.optflag(
 415                 "",
 416                 "test-builder",
 417                 "specified the rustc-like binary to use as the test builder",
 418             )
 419         }),
 420     ]
 421 }
 422
 423 fn usage(argv0: &str) {
 424     let mut options = getopts::Options::new();
 425     for option in opts() {
 426         (option.apply)(&mut options);
 427     }
 428     println!("{}", options.usage(&format!("{} [options] <input>", argv0)));
 429 }
 430
 431 fn main_args(args: &[String]) -> i32 {
 432     let mut options = getopts::Options::new();
 433     for option in opts() {
 434         (option.apply)(&mut options);
 435     }
 436     let matches = match options.parse(&args[1..]) {
 437         Ok(m) => m,
 438         Err(err) => {
 439             early_error(ErrorOutputType::default(), &err.to_string());
 440         }
 441     };
 442     let options = match config::Options::from_matches(&matches) {
 443         Ok(opts) => opts,
 444         Err(code) => return code,
 445     };
 446     rustc_interface::interface::default_thread_pool(options.edition, move || main_options(options))
 447 }
 448
 449 fn main_options(options: config::Options) -> i32 {
 450     let diag = core::new_handler(options.error_format, None, &options.debugging_options);
 451
 452     match (options.should_test, options.markdown_input()) {
 453         (true, true) => return markdown::test(options, &diag),
 454         (true, false) => return test::run(options),
 455         (false, true) => {
 456             return markdown::render(options.input, options.render_options, &diag, options.edition);
 457         }
 458         (false, false) => {}
 459     }
 460
 461     // need to move these items separately because we lose them by the time the closure is called,
 462     // but we can't crates the Handler ahead of time because it's not Send
 463     let diag_opts = (options.error_format, options.edition, options.debugging_options.clone());
 464     let show_coverage = options.show_coverage;
 465     rust_input(options, move |out| {
 466         if show_coverage {
 467             // if we ran coverage, bail early, we don't need to also generate docs at this point
 468             // (also we didn't load in any of the useful passes)
 469             return rustc_driver::EXIT_SUCCESS;
 470         }
 471
 472         let Output { krate, renderinfo, renderopts } = out;
 473         info!("going to format");
 474         let (error_format, edition, debugging_options) = diag_opts;
 475         let diag = core::new_handler(error_format, None, &debugging_options);
 476         match html::render::run(krate, renderopts, renderinfo, &diag, edition) {
 477             Ok(_) => rustc_driver::EXIT_SUCCESS,
 478             Err(e) => {
 479                 diag.struct_err(&format!("couldn't generate documentation: {}", e.error))
 480                     .note(&format!("failed to create or modify \"{}\"", e.file.display()))
 481                     .emit();
 482                 rustc_driver::EXIT_FAILURE
 483             }
 484         }
 485     })
 486 }
 487
 488 /// Interprets the input file as a rust source file, passing it through the
 489 /// compiler all the way through the analysis passes. The rustdoc output is then
 490 /// generated from the cleaned AST of the crate.
 491 ///
 492 /// This form of input will run all of the plug/cleaning passes
 493 fn rust_input<R, F>(options: config::Options, f: F) -> R
 494 where
 495     R: 'static + Send,
 496     F: 'static + Send + FnOnce(Output) -> R,
 497 {
 498     // First, parse the crate and extract all relevant information.
 499     info!("starting to run rustc");
 500
 501     let result = rustc_driver::catch_fatal_errors(move || {
 502         let crate_name = options.crate_name.clone();
 503         let crate_version = options.crate_version.clone();
 504         let (mut krate, renderinfo, renderopts) = core::run_core(options);
 505
 506         info!("finished with rustc");
 507
 508         if let Some(name) = crate_name {
 509             krate.name = name
 510         }
 511
 512         krate.version = crate_version;
 513
 514         f(Output { krate, renderinfo, renderopts })
 515     });
 516
 517     match result {
 518         Ok(output) => output,
 519         Err(_) => panic::resume_unwind(Box::new(rustc_errors::FatalErrorMarker)),
 520     }
 521 }