src/librustdoc/core.rs

   1 use rustc::middle::cstore::CrateStore;
   2 use rustc::middle::privacy::AccessLevels;
   3 use rustc::session::config::ErrorOutputType;
   4 use rustc::session::DiagnosticOutput;
   5 use rustc::session::{self, config};
   6 use rustc::ty::{Ty, TyCtxt};
   7 use rustc_data_structures::fx::{FxHashMap, FxHashSet};
   8 use rustc_driver::abort_on_err;
   9 use rustc_feature::UnstableFeatures;
  10 use rustc_hir::def::Namespace::TypeNS;
  11 use rustc_hir::def_id::{CrateNum, DefId, DefIndex, LOCAL_CRATE};
  12 use rustc_hir::HirId;
  13 use rustc_interface::interface;
  14 use rustc_resolve as resolve;
  15 use rustc_session::lint;
  16
  17 use rustc_ast::ast::CRATE_NODE_ID;
  18 use rustc_attr as attr;
  19 use rustc_errors::emitter::{Emitter, EmitterWriter};
  20 use rustc_errors::json::JsonEmitter;
  21 use rustc_span::source_map;
  22 use rustc_span::symbol::sym;
  23 use rustc_span::DUMMY_SP;
  24
  25 use rustc_data_structures::sync::{self, Lrc};
  26 use std::cell::RefCell;
  27 use std::mem;
  28 use std::rc::Rc;
  29
  30 use crate::clean;
  31 use crate::clean::{AttributesExt, MAX_DEF_ID};
  32 use crate::config::{Options as RustdocOptions, RenderOptions};
  33 use crate::html::render::RenderInfo;
  34
  35 use crate::passes::{self, Condition::*, ConditionalPass};
  36
  37 pub use rustc::session::config::{CodegenOptions, DebuggingOptions, Input, Options};
  38 pub use rustc::session::search_paths::SearchPath;
  39
  40 pub type ExternalPaths = FxHashMap<DefId, (Vec<String>, clean::TypeKind)>;
  41
  42 pub struct DocContext<'tcx> {
  43     pub tcx: TyCtxt<'tcx>,
  44     pub resolver: Rc<RefCell<interface::BoxedResolver>>,
  45     /// Later on moved into `html::render::CACHE_KEY`
  46     pub renderinfo: RefCell<RenderInfo>,
  47     /// Later on moved through `clean::Crate` into `html::render::CACHE_KEY`
  48     pub external_traits: Rc<RefCell<FxHashMap<DefId, clean::Trait>>>,
  49     /// Used while populating `external_traits` to ensure we don't process the same trait twice at
  50     /// the same time.
  51     pub active_extern_traits: RefCell<FxHashSet<DefId>>,
  52     // The current set of type and lifetime substitutions,
  53     // for expanding type aliases at the HIR level:
  54     /// Table `DefId` of type parameter -> substituted type
  55     pub ty_substs: RefCell<FxHashMap<DefId, clean::Type>>,
  56     /// Table `DefId` of lifetime parameter -> substituted lifetime
  57     pub lt_substs: RefCell<FxHashMap<DefId, clean::Lifetime>>,
  58     /// Table `DefId` of const parameter -> substituted const
  59     pub ct_substs: RefCell<FxHashMap<DefId, clean::Constant>>,
  60     /// Table synthetic type parameter for `impl Trait` in argument position -> bounds
  61     pub impl_trait_bounds: RefCell<FxHashMap<ImplTraitParam, Vec<clean::GenericBound>>>,
  62     pub fake_def_ids: RefCell<FxHashMap<CrateNum, DefId>>,
  63     pub all_fake_def_ids: RefCell<FxHashSet<DefId>>,
  64     /// Auto-trait or blanket impls processed so far, as `(self_ty, trait_def_id)`.
  65     // FIXME(eddyb) make this a `ty::TraitRef<'tcx>` set.
  66     pub generated_synthetics: RefCell<FxHashSet<(Ty<'tcx>, DefId)>>,
  67     pub auto_traits: Vec<DefId>,
  68 }
  69
  70 impl<'tcx> DocContext<'tcx> {
  71     pub fn sess(&self) -> &session::Session {
  72         &self.tcx.sess
  73     }
  74
  75     pub fn enter_resolver<F, R>(&self, f: F) -> R
  76     where
  77         F: FnOnce(&mut resolve::Resolver<'_>) -> R,
  78     {
  79         self.resolver.borrow_mut().access(f)
  80     }
  81
  82     /// Call the closure with the given parameters set as
  83     /// the substitutions for a type alias' RHS.
  84     pub fn enter_alias<F, R>(
  85         &self,
  86         ty_substs: FxHashMap<DefId, clean::Type>,
  87         lt_substs: FxHashMap<DefId, clean::Lifetime>,
  88         ct_substs: FxHashMap<DefId, clean::Constant>,
  89         f: F,
  90     ) -> R
  91     where
  92         F: FnOnce() -> R,
  93     {
  94         let (old_tys, old_lts, old_cts) = (
  95             mem::replace(&mut *self.ty_substs.borrow_mut(), ty_substs),
  96             mem::replace(&mut *self.lt_substs.borrow_mut(), lt_substs),
  97             mem::replace(&mut *self.ct_substs.borrow_mut(), ct_substs),
  98         );
  99         let r = f();
 100         *self.ty_substs.borrow_mut() = old_tys;
 101         *self.lt_substs.borrow_mut() = old_lts;
 102         *self.ct_substs.borrow_mut() = old_cts;
 103         r
 104     }
 105
 106     // This is an ugly hack, but it's the simplest way to handle synthetic impls without greatly
 107     // refactoring either librustdoc or librustc. In particular, allowing new DefIds to be
 108     // registered after the AST is constructed would require storing the defid mapping in a
 109     // RefCell, decreasing the performance for normal compilation for very little gain.
 110     //
 111     // Instead, we construct 'fake' def ids, which start immediately after the last DefId.
 112     // In the Debug impl for clean::Item, we explicitly check for fake
 113     // def ids, as we'll end up with a panic if we use the DefId Debug impl for fake DefIds
 114     pub fn next_def_id(&self, crate_num: CrateNum) -> DefId {
 115         let start_def_id = {
 116             let next_id = if crate_num == LOCAL_CRATE {
 117                 self.tcx.hir().definitions().def_path_table().next_id()
 118             } else {
 119                 self.enter_resolver(|r| r.cstore().def_path_table(crate_num).next_id())
 120             };
 121
 122             DefId { krate: crate_num, index: next_id }
 123         };
 124
 125         let mut fake_ids = self.fake_def_ids.borrow_mut();
 126
 127         let def_id = *fake_ids.entry(crate_num).or_insert(start_def_id);
 128         fake_ids.insert(
 129             crate_num,
 130             DefId { krate: crate_num, index: DefIndex::from(def_id.index.index() + 1) },
 131         );
 132
 133         MAX_DEF_ID.with(|m| {
 134             m.borrow_mut().entry(def_id.krate.clone()).or_insert(start_def_id);
 135         });
 136
 137         self.all_fake_def_ids.borrow_mut().insert(def_id);
 138
 139         def_id
 140     }
 141
 142     /// Like the function of the same name on the HIR map, but skips calling it on fake DefIds.
 143     /// (This avoids a slice-index-out-of-bounds panic.)
 144     pub fn as_local_hir_id(&self, def_id: DefId) -> Option<HirId> {
 145         if self.all_fake_def_ids.borrow().contains(&def_id) {
 146             None
 147         } else {
 148             self.tcx.hir().as_local_hir_id(def_id)
 149         }
 150     }
 151
 152     pub fn stability(&self, id: HirId) -> Option<attr::Stability> {
 153         self.tcx
 154             .hir()
 155             .opt_local_def_id(id)
 156             .and_then(|def_id| self.tcx.lookup_stability(def_id))
 157             .cloned()
 158     }
 159
 160     pub fn deprecation(&self, id: HirId) -> Option<attr::Deprecation> {
 161         self.tcx.hir().opt_local_def_id(id).and_then(|def_id| self.tcx.lookup_deprecation(def_id))
 162     }
 163 }
 164
 165 /// Creates a new diagnostic `Handler` that can be used to emit warnings and errors.
 166 ///
 167 /// If the given `error_format` is `ErrorOutputType::Json` and no `SourceMap` is given, a new one
 168 /// will be created for the handler.
 169 pub fn new_handler(
 170     error_format: ErrorOutputType,
 171     source_map: Option<Lrc<source_map::SourceMap>>,
 172     debugging_opts: &DebuggingOptions,
 173 ) -> rustc_errors::Handler {
 174     let emitter: Box<dyn Emitter + sync::Send> = match error_format {
 175         ErrorOutputType::HumanReadable(kind) => {
 176             let (short, color_config) = kind.unzip();
 177             Box::new(
 178                 EmitterWriter::stderr(
 179                     color_config,
 180                     source_map.map(|sm| sm as _),
 181                     short,
 182                     debugging_opts.teach,
 183                     debugging_opts.terminal_width,
 184                     false,
 185                 )
 186                 .ui_testing(debugging_opts.ui_testing()),
 187             )
 188         }
 189         ErrorOutputType::Json { pretty, json_rendered } => {
 190             let source_map = source_map.unwrap_or_else(|| {
 191                 Lrc::new(source_map::SourceMap::new(source_map::FilePathMapping::empty()))
 192             });
 193             Box::new(
 194                 JsonEmitter::stderr(None, source_map, pretty, json_rendered, false)
 195                     .ui_testing(debugging_opts.ui_testing()),
 196             )
 197         }
 198     };
 199
 200     rustc_errors::Handler::with_emitter_and_flags(
 201         emitter,
 202         debugging_opts.diagnostic_handler_flags(true),
 203     )
 204 }
 205
 206 pub fn run_core(options: RustdocOptions) -> (clean::Crate, RenderInfo, RenderOptions) {
 207     // Parse, resolve, and typecheck the given crate.
 208
 209     let RustdocOptions {
 210         input,
 211         crate_name,
 212         proc_macro_crate,
 213         error_format,
 214         libs,
 215         externs,
 216         mut cfgs,
 217         codegen_options,
 218         debugging_options,
 219         target,
 220         edition,
 221         maybe_sysroot,
 222         lint_opts,
 223         describe_lints,
 224         lint_cap,
 225         mut default_passes,
 226         mut document_private,
 227         document_hidden,
 228         mut manual_passes,
 229         display_warnings,
 230         render_options,
 231         ..
 232     } = options;
 233
 234     let extern_names: Vec<String> = externs
 235         .iter()
 236         .filter(|(_, entry)| entry.add_prelude)
 237         .map(|(name, _)| name)
 238         .cloned()
 239         .collect();
 240
 241     // Add the doc cfg into the doc build.
 242     cfgs.push("doc".to_string());
 243
 244     let cpath = Some(input.clone());
 245     let input = Input::File(input);
 246
 247     let intra_link_resolution_failure_name = lint::builtin::INTRA_DOC_LINK_RESOLUTION_FAILURE.name;
 248     let warnings_lint_name = lint::builtin::WARNINGS.name;
 249     let missing_docs = rustc_lint::builtin::MISSING_DOCS.name;
 250     let missing_doc_example = rustc_lint::builtin::MISSING_DOC_CODE_EXAMPLES.name;
 251     let private_doc_tests = rustc_lint::builtin::PRIVATE_DOC_TESTS.name;
 252
 253     // In addition to those specific lints, we also need to whitelist those given through
 254     // command line, otherwise they'll get ignored and we don't want that.
 255     let mut whitelisted_lints = vec![
 256         warnings_lint_name.to_owned(),
 257         intra_link_resolution_failure_name.to_owned(),
 258         missing_docs.to_owned(),
 259         missing_doc_example.to_owned(),
 260         private_doc_tests.to_owned(),
 261     ];
 262
 263     whitelisted_lints.extend(lint_opts.iter().map(|(lint, _)| lint).cloned());
 264
 265     let lints = || {
 266         lint::builtin::HardwiredLints::get_lints()
 267             .into_iter()
 268             .chain(rustc_lint::SoftLints::get_lints().into_iter())
 269     };
 270
 271     let lint_opts = lints()
 272         .filter_map(|lint| {
 273             if lint.name == warnings_lint_name || lint.name == intra_link_resolution_failure_name {
 274                 None
 275             } else {
 276                 Some((lint.name_lower(), lint::Allow))
 277             }
 278         })
 279         .chain(lint_opts.into_iter())
 280         .collect::<Vec<_>>();
 281
 282     let lint_caps = lints()
 283         .filter_map(|lint| {
 284             // We don't want to whitelist *all* lints so let's
 285             // ignore those ones.
 286             if whitelisted_lints.iter().any(|l| lint.name == l) {
 287                 None
 288             } else {
 289                 Some((lint::LintId::of(lint), lint::Allow))
 290             }
 291         })
 292         .collect();
 293
 294     let crate_types = if proc_macro_crate {
 295         vec![config::CrateType::ProcMacro]
 296     } else {
 297         vec![config::CrateType::Rlib]
 298     };
 299     // plays with error output here!
 300     let sessopts = config::Options {
 301         maybe_sysroot,
 302         search_paths: libs,
 303         crate_types,
 304         lint_opts: if !display_warnings { lint_opts } else { vec![] },
 305         lint_cap: Some(lint_cap.unwrap_or_else(|| lint::Forbid)),
 306         cg: codegen_options,
 307         externs,
 308         target_triple: target,
 309         unstable_features: UnstableFeatures::from_environment(),
 310         actually_rustdoc: true,
 311         debugging_opts: debugging_options,
 312         error_format,
 313         edition,
 314         describe_lints,
 315         ..Options::default()
 316     };
 317
 318     let config = interface::Config {
 319         opts: sessopts,
 320         crate_cfg: interface::parse_cfgspecs(cfgs),
 321         input,
 322         input_path: cpath,
 323         output_file: None,
 324         output_dir: None,
 325         file_loader: None,
 326         diagnostic_output: DiagnosticOutput::Default,
 327         stderr: None,
 328         crate_name,
 329         lint_caps,
 330         register_lints: None,
 331         override_queries: None,
 332         registry: rustc_driver::diagnostics_registry(),
 333     };
 334
 335     interface::run_compiler_in_existing_thread_pool(config, |compiler| {
 336         compiler.enter(|queries| {
 337             let sess = compiler.session();
 338
 339             // We need to hold on to the complete resolver, so we cause everything to be
 340             // cloned for the analysis passes to use. Suboptimal, but necessary in the
 341             // current architecture.
 342             let resolver = {
 343                 let parts = abort_on_err(queries.expansion(), sess).peek();
 344                 let resolver = parts.1.borrow();
 345
 346                 // Before we actually clone it, let's force all the extern'd crates to
 347                 // actually be loaded, just in case they're only referred to inside
 348                 // intra-doc-links
 349                 resolver.borrow_mut().access(|resolver| {
 350                     for extern_name in &extern_names {
 351                         resolver
 352                             .resolve_str_path_error(DUMMY_SP, extern_name, TypeNS, CRATE_NODE_ID)
 353                             .unwrap_or_else(|()| {
 354                                 panic!("Unable to resolve external crate {}", extern_name)
 355                             });
 356                     }
 357                 });
 358
 359                 // Now we're good to clone the resolver because everything should be loaded
 360                 resolver.clone()
 361             };
 362
 363             if sess.has_errors() {
 364                 sess.fatal("Compilation failed, aborting rustdoc");
 365             }
 366
 367             let mut global_ctxt = abort_on_err(queries.global_ctxt(), sess).take();
 368
 369             global_ctxt.enter(|tcx| {
 370                 tcx.analysis(LOCAL_CRATE).ok();
 371
 372                 // Abort if there were any errors so far
 373                 sess.abort_if_errors();
 374
 375                 let access_levels = tcx.privacy_access_levels(LOCAL_CRATE);
 376                 // Convert from a HirId set to a DefId set since we don't always have easy access
 377                 // to the map from defid -> hirid
 378                 let access_levels = AccessLevels {
 379                     map: access_levels
 380                         .map
 381                         .iter()
 382                         .map(|(&k, &v)| (tcx.hir().local_def_id(k), v))
 383                         .collect(),
 384                 };
 385
 386                 let mut renderinfo = RenderInfo::default();
 387                 renderinfo.access_levels = access_levels;
 388
 389                 let mut ctxt = DocContext {
 390                     tcx,
 391                     resolver,
 392                     external_traits: Default::default(),
 393                     active_extern_traits: Default::default(),
 394                     renderinfo: RefCell::new(renderinfo),
 395                     ty_substs: Default::default(),
 396                     lt_substs: Default::default(),
 397                     ct_substs: Default::default(),
 398                     impl_trait_bounds: Default::default(),
 399                     fake_def_ids: Default::default(),
 400                     all_fake_def_ids: Default::default(),
 401                     generated_synthetics: Default::default(),
 402                     auto_traits: tcx
 403                         .all_traits(LOCAL_CRATE)
 404                         .iter()
 405                         .cloned()
 406                         .filter(|trait_def_id| tcx.trait_is_auto(*trait_def_id))
 407                         .collect(),
 408                 };
 409                 debug!("crate: {:?}", tcx.hir().krate());
 410
 411                 let mut krate = clean::krate(&mut ctxt);
 412
 413                 fn report_deprecated_attr(name: &str, diag: &rustc_errors::Handler) {
 414                     let mut msg = diag.struct_warn(&format!(
 415                         "the `#![doc({})]` attribute is \
 416                                                          considered deprecated",
 417                         name
 418                     ));
 419                     msg.warn(
 420                         "see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \
 421                          for more information",
 422                     );
 423
 424                     if name == "no_default_passes" {
 425                         msg.help("you may want to use `#![doc(document_private_items)]`");
 426                     }
 427
 428                     msg.emit();
 429                 }
 430
 431                 // Process all of the crate attributes, extracting plugin metadata along
 432                 // with the passes which we are supposed to run.
 433                 for attr in krate.module.as_ref().unwrap().attrs.lists(sym::doc) {
 434                     let diag = ctxt.sess().diagnostic();
 435
 436                     let name = attr.name_or_empty();
 437                     if attr.is_word() {
 438                         if name == sym::no_default_passes {
 439                             report_deprecated_attr("no_default_passes", diag);
 440                             if default_passes == passes::DefaultPassOption::Default {
 441                                 default_passes = passes::DefaultPassOption::None;
 442                             }
 443                         }
 444                     } else if let Some(value) = attr.value_str() {
 445                         let sink = match name {
 446                             sym::passes => {
 447                                 report_deprecated_attr("passes = \"...\"", diag);
 448                                 &mut manual_passes
 449                             }
 450                             sym::plugins => {
 451                                 report_deprecated_attr("plugins = \"...\"", diag);
 452                                 eprintln!(
 453                                     "WARNING: `#![doc(plugins = \"...\")]` \
 454                                       no longer functions; see CVE-2018-1000622"
 455                                 );
 456                                 continue;
 457                             }
 458                             _ => continue,
 459                         };
 460                         for name in value.as_str().split_whitespace() {
 461                             sink.push(name.to_string());
 462                         }
 463                     }
 464
 465                     if attr.is_word() && name == sym::document_private_items {
 466                         document_private = true;
 467                     }
 468                 }
 469
 470                 let passes = passes::defaults(default_passes).iter().copied().chain(
 471                     manual_passes.into_iter().flat_map(|name| {
 472                         if let Some(pass) = passes::find_pass(&name) {
 473                             Some(ConditionalPass::always(pass))
 474                         } else {
 475                             error!("unknown pass {}, skipping", name);
 476                             None
 477                         }
 478                     }),
 479                 );
 480
 481                 info!("Executing passes");
 482
 483                 for p in passes {
 484                     let run = match p.condition {
 485                         Always => true,
 486                         WhenDocumentPrivate => document_private,
 487                         WhenNotDocumentPrivate => !document_private,
 488                         WhenNotDocumentHidden => !document_hidden,
 489                     };
 490                     if run {
 491                         debug!("running pass {}", p.pass.name);
 492                         krate = (p.pass.run)(krate, &ctxt);
 493                     }
 494                 }
 495
 496                 ctxt.sess().abort_if_errors();
 497
 498                 (krate, ctxt.renderinfo.into_inner(), render_options)
 499             })
 500         })
 501     })
 502 }
 503
 504 /// `DefId` or parameter index (`ty::ParamTy.index`) of a synthetic type parameter
 505 /// for `impl Trait` in argument position.
 506 #[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
 507 pub enum ImplTraitParam {
 508     DefId(DefId),
 509     ParamIndex(u32),
 510 }
 511
 512 impl From<DefId> for ImplTraitParam {
 513     fn from(did: DefId) -> Self {
 514         ImplTraitParam::DefId(did)
 515     }
 516 }
 517
 518 impl From<u32> for ImplTraitParam {
 519     fn from(idx: u32) -> Self {
 520         ImplTraitParam::ParamIndex(idx)
 521     }
 522 }