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(arbitrary_self_types)]
   7 #![feature(box_patterns)]
   8 #![feature(box_syntax)]
   9 #![feature(in_band_lifetimes)]
  10 #![feature(nll)]
  11 #![feature(set_stdio)]
  12 #![feature(test)]
  13 #![feature(ptr_offset_from)]
  14 #![feature(crate_visibility_modifier)]
  15 #![feature(const_fn)]
  16 #![feature(drain_filter)]
  17 #![feature(never_type)]
  18 #![feature(unicode_internals)]
  19 #![recursion_limit = "256"]
  20
  21 extern crate env_logger;
  22 extern crate getopts;
  23 extern crate rustc;
  24 extern crate rustc_data_structures;
  25 extern crate rustc_driver;
  26 extern crate rustc_error_codes;
  27 extern crate rustc_expand;
  28 extern crate rustc_feature;
  29 extern crate rustc_index;
  30 extern crate rustc_interface;
  31 extern crate rustc_lexer;
  32 extern crate rustc_lint;
  33 extern crate rustc_metadata;
  34 extern crate rustc_parse;
  35 extern crate rustc_resolve;
  36 extern crate rustc_span as rustc_span;
  37 extern crate rustc_target;
  38 extern crate rustc_typeck;
  39 extern crate syntax;
  40 extern crate test as testing;
  41 #[macro_use]
  42 extern crate log;
  43 extern crate rustc_errors as errors;
  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         stable("test", |o| o.optflag("", "test", "run code examples as tests")),
 176         stable("test-args", |o| {
 177             o.optmulti("", "test-args", "arguments to pass to the test runner", "ARGS")
 178         }),
 179         stable("target", |o| o.optopt("", "target", "target triple to document", "TRIPLE")),
 180         stable("markdown-css", |o| {
 181             o.optmulti(
 182                 "",
 183                 "markdown-css",
 184                 "CSS files to include via <link> in a rendered Markdown file",
 185                 "FILES",
 186             )
 187         }),
 188         stable("html-in-header", |o| {
 189             o.optmulti(
 190                 "",
 191                 "html-in-header",
 192                 "files to include inline in the <head> section of a rendered Markdown file \
 193                         or generated documentation",
 194                 "FILES",
 195             )
 196         }),
 197         stable("html-before-content", |o| {
 198             o.optmulti(
 199                 "",
 200                 "html-before-content",
 201                 "files to include inline between <body> and the content of a rendered \
 202                         Markdown file or generated documentation",
 203                 "FILES",
 204             )
 205         }),
 206         stable("html-after-content", |o| {
 207             o.optmulti(
 208                 "",
 209                 "html-after-content",
 210                 "files to include inline between the content and </body> of a rendered \
 211                         Markdown file or generated documentation",
 212                 "FILES",
 213             )
 214         }),
 215         unstable("markdown-before-content", |o| {
 216             o.optmulti(
 217                 "",
 218                 "markdown-before-content",
 219                 "files to include inline between <body> and the content of a rendered \
 220                         Markdown file or generated documentation",
 221                 "FILES",
 222             )
 223         }),
 224         unstable("markdown-after-content", |o| {
 225             o.optmulti(
 226                 "",
 227                 "markdown-after-content",
 228                 "files to include inline between the content and </body> of a rendered \
 229                         Markdown file or generated documentation",
 230                 "FILES",
 231             )
 232         }),
 233         stable("markdown-playground-url", |o| {
 234             o.optopt("", "markdown-playground-url", "URL to send code snippets to", "URL")
 235         }),
 236         stable("markdown-no-toc", |o| {
 237             o.optflag("", "markdown-no-toc", "don't include table of contents")
 238         }),
 239         stable("e", |o| {
 240             o.optopt(
 241                 "e",
 242                 "extend-css",
 243                 "To add some CSS rules with a given file to generate doc with your \
 244                       own theme. However, your theme might break if the rustdoc's generated HTML \
 245                       changes, so be careful!",
 246                 "PATH",
 247             )
 248         }),
 249         unstable("Z", |o| {
 250             o.optmulti("Z", "", "internal and debugging options (only on nightly build)", "FLAG")
 251         }),
 252         stable("sysroot", |o| o.optopt("", "sysroot", "Override the system root", "PATH")),
 253         unstable("playground-url", |o| {
 254             o.optopt(
 255                 "",
 256                 "playground-url",
 257                 "URL to send code snippets to, may be reset by --markdown-playground-url \
 258                       or `#![doc(html_playground_url=...)]`",
 259                 "URL",
 260             )
 261         }),
 262         unstable("display-warnings", |o| {
 263             o.optflag("", "display-warnings", "to print code warnings when testing doc")
 264         }),
 265         unstable("crate-version", |o| {
 266             o.optopt("", "crate-version", "crate version to print into documentation", "VERSION")
 267         }),
 268         unstable("sort-modules-by-appearance", |o| {
 269             o.optflag(
 270                 "",
 271                 "sort-modules-by-appearance",
 272                 "sort modules by where they appear in the \
 273                                                          program, rather than alphabetically",
 274             )
 275         }),
 276         stable("theme", |o| {
 277             o.optmulti(
 278                 "",
 279                 "theme",
 280                 "additional themes which will be added to the generated docs",
 281                 "FILES",
 282             )
 283         }),
 284         stable("check-theme", |o| {
 285             o.optmulti("", "check-theme", "check if given theme is valid", "FILES")
 286         }),
 287         unstable("resource-suffix", |o| {
 288             o.optopt(
 289                 "",
 290                 "resource-suffix",
 291                 "suffix to add to CSS and JavaScript files, e.g., \"light.css\" will become \
 292                       \"light-suffix.css\"",
 293                 "PATH",
 294             )
 295         }),
 296         stable("edition", |o| {
 297             o.optopt(
 298                 "",
 299                 "edition",
 300                 "edition to use when compiling rust code (default: 2015)",
 301                 "EDITION",
 302             )
 303         }),
 304         stable("color", |o| {
 305             o.optopt(
 306                 "",
 307                 "color",
 308                 "Configure coloring of output:
 309                                           auto   = colorize, if output goes to a tty (default);
 310                                           always = always colorize output;
 311                                           never  = never colorize output",
 312                 "auto|always|never",
 313             )
 314         }),
 315         stable("error-format", |o| {
 316             o.optopt(
 317                 "",
 318                 "error-format",
 319                 "How errors and other messages are produced",
 320                 "human|json|short",
 321             )
 322         }),
 323         stable("json", |o| {
 324             o.optopt("", "json", "Configure the structure of JSON diagnostics", "CONFIG")
 325         }),
 326         unstable("disable-minification", |o| {
 327             o.optflag("", "disable-minification", "Disable minification applied on JS files")
 328         }),
 329         stable("warn", |o| o.optmulti("W", "warn", "Set lint warnings", "OPT")),
 330         stable("allow", |o| o.optmulti("A", "allow", "Set lint allowed", "OPT")),
 331         stable("deny", |o| o.optmulti("D", "deny", "Set lint denied", "OPT")),
 332         stable("forbid", |o| o.optmulti("F", "forbid", "Set lint forbidden", "OPT")),
 333         stable("cap-lints", |o| {
 334             o.optmulti(
 335                 "",
 336                 "cap-lints",
 337                 "Set the most restrictive lint level. \
 338                  More restrictive lints are capped at this \
 339                  level. By default, it is at `forbid` level.",
 340                 "LEVEL",
 341             )
 342         }),
 343         unstable("index-page", |o| {
 344             o.optopt("", "index-page", "Markdown file to be used as index page", "PATH")
 345         }),
 346         unstable("enable-index-page", |o| {
 347             o.optflag("", "enable-index-page", "To enable generation of the index page")
 348         }),
 349         unstable("static-root-path", |o| {
 350             o.optopt(
 351                 "",
 352                 "static-root-path",
 353                 "Path string to force loading static files from in output pages. \
 354                       If not set, uses combinations of '../' to reach the documentation root.",
 355                 "PATH",
 356             )
 357         }),
 358         unstable("disable-per-crate-search", |o| {
 359             o.optflag(
 360                 "",
 361                 "disable-per-crate-search",
 362                 "disables generating the crate selector on the search box",
 363             )
 364         }),
 365         unstable("persist-doctests", |o| {
 366             o.optopt(
 367                 "",
 368                 "persist-doctests",
 369                 "Directory to persist doctest executables into",
 370                 "PATH",
 371             )
 372         }),
 373         unstable("generate-redirect-pages", |o| {
 374             o.optflag(
 375                 "",
 376                 "generate-redirect-pages",
 377                 "Generate extra pages to support legacy URLs and tool links",
 378             )
 379         }),
 380         unstable("show-coverage", |o| {
 381             o.optflag(
 382                 "",
 383                 "show-coverage",
 384                 "calculate percentage of public items with documentation",
 385             )
 386         }),
 387         unstable("enable-per-target-ignores", |o| {
 388             o.optflag(
 389                 "",
 390                 "enable-per-target-ignores",
 391                 "parse ignore-foo for ignoring doctests on a per-target basis",
 392             )
 393         }),
 394         unstable("runtool", |o| {
 395             o.optopt(
 396                 "",
 397                 "runtool",
 398                 "",
 399                 "The tool to run tests with when building for a different target than host",
 400             )
 401         }),
 402         unstable("runtool-arg", |o| {
 403             o.optmulti(
 404                 "",
 405                 "runtool-arg",
 406                 "",
 407                 "One (of possibly many) arguments to pass to the runtool",
 408             )
 409         }),
 410         unstable("test-builder", |o| {
 411             o.optflag(
 412                 "",
 413                 "test-builder",
 414                 "specified the rustc-like binary to use as the test builder",
 415             )
 416         }),
 417     ]
 418 }
 419
 420 fn usage(argv0: &str) {
 421     let mut options = getopts::Options::new();
 422     for option in opts() {
 423         (option.apply)(&mut options);
 424     }
 425     println!("{}", options.usage(&format!("{} [options] <input>", argv0)));
 426 }
 427
 428 fn main_args(args: &[String]) -> i32 {
 429     let mut options = getopts::Options::new();
 430     for option in opts() {
 431         (option.apply)(&mut options);
 432     }
 433     let matches = match options.parse(&args[1..]) {
 434         Ok(m) => m,
 435         Err(err) => {
 436             early_error(ErrorOutputType::default(), &err.to_string());
 437         }
 438     };
 439     let options = match config::Options::from_matches(&matches) {
 440         Ok(opts) => opts,
 441         Err(code) => return code,
 442     };
 443     rustc_interface::interface::default_thread_pool(options.edition, move || main_options(options))
 444 }
 445
 446 fn main_options(options: config::Options) -> i32 {
 447     let diag = core::new_handler(options.error_format, None, &options.debugging_options);
 448
 449     match (options.should_test, options.markdown_input()) {
 450         (true, true) => return markdown::test(options, &diag),
 451         (true, false) => return test::run(options),
 452         (false, true) => {
 453             return markdown::render(options.input, options.render_options, &diag, options.edition);
 454         }
 455         (false, false) => {}
 456     }
 457
 458     // need to move these items separately because we lose them by the time the closure is called,
 459     // but we can't crates the Handler ahead of time because it's not Send
 460     let diag_opts = (options.error_format, options.edition, options.debugging_options.clone());
 461     let show_coverage = options.show_coverage;
 462     rust_input(options, move |out| {
 463         if show_coverage {
 464             // if we ran coverage, bail early, we don't need to also generate docs at this point
 465             // (also we didn't load in any of the useful passes)
 466             return rustc_driver::EXIT_SUCCESS;
 467         }
 468
 469         let Output { krate, renderinfo, renderopts } = out;
 470         info!("going to format");
 471         let (error_format, edition, debugging_options) = diag_opts;
 472         let diag = core::new_handler(error_format, None, &debugging_options);
 473         match html::render::run(krate, renderopts, renderinfo, &diag, edition) {
 474             Ok(_) => rustc_driver::EXIT_SUCCESS,
 475             Err(e) => {
 476                 diag.struct_err(&format!("couldn't generate documentation: {}", e.error))
 477                     .note(&format!("failed to create or modify \"{}\"", e.file.display()))
 478                     .emit();
 479                 rustc_driver::EXIT_FAILURE
 480             }
 481         }
 482     })
 483 }
 484
 485 /// Interprets the input file as a rust source file, passing it through the
 486 /// compiler all the way through the analysis passes. The rustdoc output is then
 487 /// generated from the cleaned AST of the crate.
 488 ///
 489 /// This form of input will run all of the plug/cleaning passes
 490 fn rust_input<R, F>(options: config::Options, f: F) -> R
 491 where
 492     R: 'static + Send,
 493     F: 'static + Send + FnOnce(Output) -> R,
 494 {
 495     // First, parse the crate and extract all relevant information.
 496     info!("starting to run rustc");
 497
 498     let result = rustc_driver::catch_fatal_errors(move || {
 499         let crate_name = options.crate_name.clone();
 500         let crate_version = options.crate_version.clone();
 501         let (mut krate, renderinfo, renderopts) = core::run_core(options);
 502
 503         info!("finished with rustc");
 504
 505         if let Some(name) = crate_name {
 506             krate.name = name
 507         }
 508
 509         krate.version = crate_version;
 510
 511         f(Output { krate, renderinfo, renderopts })
 512     });
 513
 514     match result {
 515         Ok(output) => output,
 516         Err(_) => panic::resume_unwind(Box::new(errors::FatalErrorMarker)),
 517     }
 518 }