1 // Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
11 //! Lints, aka compiler warnings.
13 //! A 'lint' check is a kind of miscellaneous constraint that a user _might_
14 //! want to enforce, but might reasonably want to permit as well, on a
15 //! module-by-module basis. They contrast with static constraints enforced by
16 //! other phases of the compiler, which are generally required to hold in order
17 //! to compile the program at all.
19 //! Most lints can be written as `LintPass` instances. These run just before
20 //! translation to LLVM bytecode. The `LintPass`es built into rustc are defined
21 //! within `builtin.rs`, which has further comments on how to add such a lint.
22 //! rustc can also load user-defined lint plugins via the plugin mechanism.
24 //! Some of rustc's lints are defined elsewhere in the compiler and work by
25 //! calling `add_lint()` on the overall `Session` object. This works when
26 //! it happens before the main lint pass, which emits the lints stored by
27 //! `add_lint()`. To emit lints after the main lint pass (from trans, for
28 //! example) requires more effort. See `emit_lint` and `GatherNodeLevels`
31 pub use self::Level::*;
32 pub use self::LintSource::*;
36 use errors::DiagnosticBuilder;
37 use hir::def_id::{CrateNum, LOCAL_CRATE};
38 use hir::intravisit::{self, FnKind};
41 use std::ascii::AsciiExt;
44 use syntax::codemap::MultiSpan;
45 use syntax::symbol::Symbol;
46 use syntax::visit as ast_visit;
49 use ty::maps::Providers;
50 use util::nodemap::NodeMap;
52 pub use lint::context::{LateContext, EarlyContext, LintContext, LintStore,
53 check_crate, check_ast_crate,
54 FutureIncompatibleInfo, BufferedEarlyLint};
56 /// Specification of a single lint.
57 #[derive(Copy, Clone, Debug)]
59 /// A string identifier for the lint.
61 /// This identifies the lint in attributes and in command-line arguments.
62 /// In those contexts it is always lowercase, but this field is compared
63 /// in a way which is case-insensitive for ASCII characters. This allows
64 /// `declare_lint!()` invocations to follow the convention of upper-case
65 /// statics without repeating the name.
67 /// The name is written with underscores, e.g. "unused_imports".
68 /// On the command line, underscores become dashes.
69 pub name: &'static str,
71 /// Default level for the lint.
72 pub default_level: Level,
74 /// Description of the lint or the issue it detects.
76 /// e.g. "imports that are never used"
77 pub desc: &'static str,
81 /// Get the lint's name, with ASCII letters converted to lowercase.
82 pub fn name_lower(&self) -> String {
83 self.name.to_ascii_lowercase()
87 /// Build a `Lint` initializer.
89 macro_rules! lint_initializer {
90 ($name:ident, $level:ident, $desc:expr) => (
92 name: stringify!($name),
93 default_level: ::rustc::lint::$level,
99 /// Declare a static item of type `&'static Lint`.
101 macro_rules! declare_lint {
102 (pub $name:ident, $level:ident, $desc:expr) => (
103 pub static $name: &'static ::rustc::lint::Lint
104 = &lint_initializer!($name, $level, $desc);
106 ($name:ident, $level:ident, $desc:expr) => (
107 static $name: &'static ::rustc::lint::Lint
108 = &lint_initializer!($name, $level, $desc);
112 /// Declare a static `LintArray` and return it as an expression.
114 macro_rules! lint_array { ($( $lint:expr ),*) => (
116 static ARRAY: LintArray = &[ $( &$lint ),* ];
121 pub type LintArray = &'static [&'static &'static Lint];
124 /// Get descriptions of the lints this `LintPass` object can emit.
126 /// NB: there is no enforcement that the object only emits lints it registered.
127 /// And some `rustc` internal `LintPass`es register lints to be emitted by other
128 /// parts of the compiler. If you want enforced access restrictions for your
129 /// `Lint`, make it a private `static` item in its own module.
130 fn get_lints(&self) -> LintArray;
134 /// Trait for types providing lint checks.
136 /// Each `check` method checks a single syntax node, and should not
137 /// invoke methods recursively (unlike `Visitor`). By default they
140 // FIXME: eliminate the duplication with `Visitor`. But this also
141 // contains a few lint-specific methods with no equivalent in `Visitor`.
142 pub trait LateLintPass<'a, 'tcx>: LintPass {
143 fn check_body(&mut self, _: &LateContext, _: &'tcx hir::Body) { }
144 fn check_body_post(&mut self, _: &LateContext, _: &'tcx hir::Body) { }
145 fn check_name(&mut self, _: &LateContext, _: Span, _: ast::Name) { }
146 fn check_crate(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::Crate) { }
147 fn check_crate_post(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::Crate) { }
148 fn check_mod(&mut self,
149 _: &LateContext<'a, 'tcx>,
153 fn check_mod_post(&mut self,
154 _: &LateContext<'a, 'tcx>,
158 fn check_foreign_item(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::ForeignItem) { }
159 fn check_foreign_item_post(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::ForeignItem) { }
160 fn check_item(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::Item) { }
161 fn check_item_post(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::Item) { }
162 fn check_local(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::Local) { }
163 fn check_block(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::Block) { }
164 fn check_block_post(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::Block) { }
165 fn check_stmt(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::Stmt) { }
166 fn check_arm(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::Arm) { }
167 fn check_pat(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::Pat) { }
168 fn check_decl(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::Decl) { }
169 fn check_expr(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::Expr) { }
170 fn check_expr_post(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::Expr) { }
171 fn check_ty(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::Ty) { }
172 fn check_generics(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::Generics) { }
173 fn check_fn(&mut self,
174 _: &LateContext<'a, 'tcx>,
176 _: &'tcx hir::FnDecl,
180 fn check_fn_post(&mut self,
181 _: &LateContext<'a, 'tcx>,
183 _: &'tcx hir::FnDecl,
187 fn check_trait_item(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::TraitItem) { }
188 fn check_trait_item_post(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::TraitItem) { }
189 fn check_impl_item(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::ImplItem) { }
190 fn check_impl_item_post(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::ImplItem) { }
191 fn check_struct_def(&mut self,
192 _: &LateContext<'a, 'tcx>,
193 _: &'tcx hir::VariantData,
195 _: &'tcx hir::Generics,
197 fn check_struct_def_post(&mut self,
198 _: &LateContext<'a, 'tcx>,
199 _: &'tcx hir::VariantData,
201 _: &'tcx hir::Generics,
203 fn check_struct_field(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::StructField) { }
204 fn check_variant(&mut self,
205 _: &LateContext<'a, 'tcx>,
206 _: &'tcx hir::Variant,
207 _: &'tcx hir::Generics) { }
208 fn check_variant_post(&mut self,
209 _: &LateContext<'a, 'tcx>,
210 _: &'tcx hir::Variant,
211 _: &'tcx hir::Generics) { }
212 fn check_lifetime(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::Lifetime) { }
213 fn check_lifetime_def(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::LifetimeDef) { }
214 fn check_path(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx hir::Path, _: ast::NodeId) { }
215 fn check_attribute(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx ast::Attribute) { }
217 /// Called when entering a syntax node that can have lint attributes such
218 /// as `#[allow(...)]`. Called with *all* the attributes of that node.
219 fn enter_lint_attrs(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx [ast::Attribute]) { }
221 /// Counterpart to `enter_lint_attrs`.
222 fn exit_lint_attrs(&mut self, _: &LateContext<'a, 'tcx>, _: &'tcx [ast::Attribute]) { }
225 pub trait EarlyLintPass: LintPass {
226 fn check_ident(&mut self, _: &EarlyContext, _: Span, _: ast::Ident) { }
227 fn check_crate(&mut self, _: &EarlyContext, _: &ast::Crate) { }
228 fn check_crate_post(&mut self, _: &EarlyContext, _: &ast::Crate) { }
229 fn check_mod(&mut self, _: &EarlyContext, _: &ast::Mod, _: Span, _: ast::NodeId) { }
230 fn check_mod_post(&mut self, _: &EarlyContext, _: &ast::Mod, _: Span, _: ast::NodeId) { }
231 fn check_foreign_item(&mut self, _: &EarlyContext, _: &ast::ForeignItem) { }
232 fn check_foreign_item_post(&mut self, _: &EarlyContext, _: &ast::ForeignItem) { }
233 fn check_item(&mut self, _: &EarlyContext, _: &ast::Item) { }
234 fn check_item_post(&mut self, _: &EarlyContext, _: &ast::Item) { }
235 fn check_local(&mut self, _: &EarlyContext, _: &ast::Local) { }
236 fn check_block(&mut self, _: &EarlyContext, _: &ast::Block) { }
237 fn check_block_post(&mut self, _: &EarlyContext, _: &ast::Block) { }
238 fn check_stmt(&mut self, _: &EarlyContext, _: &ast::Stmt) { }
239 fn check_arm(&mut self, _: &EarlyContext, _: &ast::Arm) { }
240 fn check_pat(&mut self, _: &EarlyContext, _: &ast::Pat) { }
241 fn check_expr(&mut self, _: &EarlyContext, _: &ast::Expr) { }
242 fn check_expr_post(&mut self, _: &EarlyContext, _: &ast::Expr) { }
243 fn check_ty(&mut self, _: &EarlyContext, _: &ast::Ty) { }
244 fn check_generics(&mut self, _: &EarlyContext, _: &ast::Generics) { }
245 fn check_fn(&mut self, _: &EarlyContext,
246 _: ast_visit::FnKind, _: &ast::FnDecl, _: Span, _: ast::NodeId) { }
247 fn check_fn_post(&mut self, _: &EarlyContext,
248 _: ast_visit::FnKind, _: &ast::FnDecl, _: Span, _: ast::NodeId) { }
249 fn check_trait_item(&mut self, _: &EarlyContext, _: &ast::TraitItem) { }
250 fn check_trait_item_post(&mut self, _: &EarlyContext, _: &ast::TraitItem) { }
251 fn check_impl_item(&mut self, _: &EarlyContext, _: &ast::ImplItem) { }
252 fn check_impl_item_post(&mut self, _: &EarlyContext, _: &ast::ImplItem) { }
253 fn check_struct_def(&mut self, _: &EarlyContext,
254 _: &ast::VariantData, _: ast::Ident, _: &ast::Generics, _: ast::NodeId) { }
255 fn check_struct_def_post(&mut self, _: &EarlyContext,
256 _: &ast::VariantData, _: ast::Ident, _: &ast::Generics, _: ast::NodeId) { }
257 fn check_struct_field(&mut self, _: &EarlyContext, _: &ast::StructField) { }
258 fn check_variant(&mut self, _: &EarlyContext, _: &ast::Variant, _: &ast::Generics) { }
259 fn check_variant_post(&mut self, _: &EarlyContext, _: &ast::Variant, _: &ast::Generics) { }
260 fn check_lifetime(&mut self, _: &EarlyContext, _: &ast::Lifetime) { }
261 fn check_lifetime_def(&mut self, _: &EarlyContext, _: &ast::LifetimeDef) { }
262 fn check_path(&mut self, _: &EarlyContext, _: &ast::Path, _: ast::NodeId) { }
263 fn check_path_list_item(&mut self, _: &EarlyContext, _: &ast::PathListItem) { }
264 fn check_attribute(&mut self, _: &EarlyContext, _: &ast::Attribute) { }
266 /// Called when entering a syntax node that can have lint attributes such
267 /// as `#[allow(...)]`. Called with *all* the attributes of that node.
268 fn enter_lint_attrs(&mut self, _: &EarlyContext, _: &[ast::Attribute]) { }
270 /// Counterpart to `enter_lint_attrs`.
271 fn exit_lint_attrs(&mut self, _: &EarlyContext, _: &[ast::Attribute]) { }
274 /// A lint pass boxed up as a trait object.
275 pub type EarlyLintPassObject = Box<EarlyLintPass + 'static>;
276 pub type LateLintPassObject = Box<for<'a, 'tcx> LateLintPass<'a, 'tcx> + 'static>;
278 /// Identifies a lint known to the compiler.
279 #[derive(Clone, Copy, Debug)]
281 // Identity is based on pointer equality of this field.
285 impl PartialEq for LintId {
286 fn eq(&self, other: &LintId) -> bool {
287 (self.lint as *const Lint) == (other.lint as *const Lint)
291 impl Eq for LintId { }
293 impl hash::Hash for LintId {
294 fn hash<H: hash::Hasher>(&self, state: &mut H) {
295 let ptr = self.lint as *const Lint;
301 /// Get the `LintId` for a `Lint`.
302 pub fn of(lint: &'static Lint) -> LintId {
308 pub fn lint_name_raw(&self) -> &'static str {
312 /// Get the name of the lint.
313 pub fn to_string(&self) -> String {
314 self.lint.name_lower()
318 /// Setting for how to handle a lint.
319 #[derive(Clone, Copy, PartialEq, PartialOrd, Eq, Ord, Debug, Hash)]
321 Allow, Warn, Deny, Forbid
324 impl_stable_hash_for!(enum self::Level {
332 /// Convert a level to a lower-case string.
333 pub fn as_str(self) -> &'static str {
342 /// Convert a lower-case string to a level.
343 pub fn from_str(x: &str) -> Option<Level> {
345 "allow" => Some(Allow),
346 "warn" => Some(Warn),
347 "deny" => Some(Deny),
348 "forbid" => Some(Forbid),
354 /// How a lint level was set.
355 #[derive(Clone, Copy, PartialEq, Eq)]
356 pub enum LintSource {
357 /// Lint is at the default level as declared
358 /// in rustc or a plugin.
361 /// Lint level was set by an attribute.
362 Node(ast::Name, Span),
364 /// Lint level was set by a command-line flag.
368 impl_stable_hash_for!(enum self::LintSource {
374 pub type LevelSource = (Level, LintSource);
380 pub use self::levels::{LintLevelSets, LintLevelMap};
382 pub struct LintBuffer {
383 map: NodeMap<Vec<BufferedEarlyLint>>,
387 pub fn new() -> LintBuffer {
388 LintBuffer { map: NodeMap() }
391 pub fn add_lint(&mut self,
396 let early_lint = BufferedEarlyLint {
397 lint_id: LintId::of(lint),
400 msg: msg.to_string(),
402 let arr = self.map.entry(id).or_insert(Vec::new());
403 if !arr.contains(&early_lint) {
404 arr.push(early_lint);
408 pub fn take(&mut self, id: ast::NodeId) -> Vec<BufferedEarlyLint> {
409 self.map.remove(&id).unwrap_or(Vec::new())
412 pub fn get_any(&self) -> Option<&[BufferedEarlyLint]> {
413 let key = self.map.keys().next().map(|k| *k);
414 key.map(|k| &self.map[&k][..])
418 pub fn struct_lint_level<'a>(sess: &'a Session,
422 span: Option<MultiSpan>,
424 -> DiagnosticBuilder<'a>
426 let mut err = match (level, span) {
427 (Level::Allow, _) => return sess.diagnostic().struct_dummy(),
428 (Level::Warn, Some(span)) => sess.struct_span_warn(span, msg),
429 (Level::Warn, None) => sess.struct_warn(msg),
430 (Level::Deny, Some(span)) |
431 (Level::Forbid, Some(span)) => sess.struct_span_err(span, msg),
432 (Level::Deny, None) |
433 (Level::Forbid, None) => sess.struct_err(msg),
436 let name = lint.name_lower();
438 LintSource::Default => {
442 &format!("#[{}({})] on by default", level.as_str(), name));
444 LintSource::CommandLine(lint_flag_val) => {
445 let flag = match level {
448 Level::Forbid => "-F",
449 Level::Allow => panic!(),
451 let hyphen_case_lint_name = name.replace("_", "-");
452 if lint_flag_val.as_str() == name {
456 &format!("requested on the command line with `{} {}`",
457 flag, hyphen_case_lint_name));
459 let hyphen_case_flag_val = lint_flag_val.as_str().replace("_", "-");
463 &format!("`{} {}` implied by `{} {}`",
464 flag, hyphen_case_lint_name, flag,
465 hyphen_case_flag_val));
468 LintSource::Node(lint_attr_name, src) => {
469 sess.diag_span_note_once(&mut err, lint, src, "lint level defined here");
470 if lint_attr_name.as_str() != name {
471 let level_str = level.as_str();
472 sess.diag_note_once(&mut err, lint,
473 &format!("#[{}({})] implied by #[{}({})]",
474 level_str, name, level_str, lint_attr_name));
479 // Check for future incompatibility lints and issue a stronger warning.
480 let lints = sess.lint_store.borrow();
481 if let Some(future_incompatible) = lints.future_incompatible(LintId::of(lint)) {
482 let explanation = format!("this was previously accepted by the compiler \
483 but is being phased out; \
484 it will become a hard error in a future release!");
485 let citation = format!("for more information, see {}",
486 future_incompatible.reference);
487 err.warn(&explanation);
494 fn lint_levels<'a, 'tcx>(tcx: TyCtxt<'a, 'tcx, 'tcx>, cnum: CrateNum)
497 assert_eq!(cnum, LOCAL_CRATE);
498 let mut builder = LintLevelMapBuilder {
499 levels: LintLevelSets::builder(tcx.sess),
502 let krate = tcx.hir.krate();
504 builder.with_lint_attrs(ast::CRATE_NODE_ID, &krate.attrs, |builder| {
505 intravisit::walk_crate(builder, krate);
508 Rc::new(builder.levels.build_map())
511 struct LintLevelMapBuilder<'a, 'tcx: 'a> {
512 levels: levels::LintLevelsBuilder<'tcx>,
513 tcx: TyCtxt<'a, 'tcx, 'tcx>,
516 impl<'a, 'tcx> LintLevelMapBuilder<'a, 'tcx> {
517 fn with_lint_attrs<F>(&mut self,
519 attrs: &[ast::Attribute],
521 where F: FnOnce(&mut Self)
523 let push = self.levels.push(attrs);
524 self.levels.register_id(self.tcx.hir.definitions().node_to_hir_id(id));
526 self.levels.pop(push);
530 impl<'a, 'tcx> intravisit::Visitor<'tcx> for LintLevelMapBuilder<'a, 'tcx> {
531 fn nested_visit_map<'this>(&'this mut self) -> intravisit::NestedVisitorMap<'this, 'tcx> {
532 intravisit::NestedVisitorMap::All(&self.tcx.hir)
535 fn visit_item(&mut self, it: &'tcx hir::Item) {
536 self.with_lint_attrs(it.id, &it.attrs, |builder| {
537 intravisit::walk_item(builder, it);
541 fn visit_foreign_item(&mut self, it: &'tcx hir::ForeignItem) {
542 self.with_lint_attrs(it.id, &it.attrs, |builder| {
543 intravisit::walk_foreign_item(builder, it);
547 fn visit_expr(&mut self, e: &'tcx hir::Expr) {
548 self.with_lint_attrs(e.id, &e.attrs, |builder| {
549 intravisit::walk_expr(builder, e);
553 fn visit_struct_field(&mut self, s: &'tcx hir::StructField) {
554 self.with_lint_attrs(s.id, &s.attrs, |builder| {
555 intravisit::walk_struct_field(builder, s);
559 fn visit_variant(&mut self,
560 v: &'tcx hir::Variant,
561 g: &'tcx hir::Generics,
562 item_id: ast::NodeId) {
563 self.with_lint_attrs(v.node.data.id(), &v.node.attrs, |builder| {
564 intravisit::walk_variant(builder, v, g, item_id);
568 fn visit_local(&mut self, l: &'tcx hir::Local) {
569 self.with_lint_attrs(l.id, &l.attrs, |builder| {
570 intravisit::walk_local(builder, l);
574 fn visit_trait_item(&mut self, trait_item: &'tcx hir::TraitItem) {
575 self.with_lint_attrs(trait_item.id, &trait_item.attrs, |builder| {
576 intravisit::walk_trait_item(builder, trait_item);
580 fn visit_impl_item(&mut self, impl_item: &'tcx hir::ImplItem) {
581 self.with_lint_attrs(impl_item.id, &impl_item.attrs, |builder| {
582 intravisit::walk_impl_item(builder, impl_item);
587 pub fn provide(providers: &mut Providers) {
588 providers.lint_levels = lint_levels;