1 // Copyright 2013 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.
13 //! This modules implements the gating necessary for preventing certain compiler
14 //! features from being used by default. This module will crawl a pre-expanded
15 //! AST to ensure that there are no features which are used that are not
18 //! Features are enabled in programs via the crate-level attributes of
19 //! `#![feature(...)]` with a comma-separated list of features.
21 //! For the purpose of future feature-tracking, once code for detection of feature
22 //! gate usage is added, *do not remove it again* even once the feature
26 use self::AttributeType::*;
28 use abi::RustIntrinsic;
32 use attr::AttrMetaMethods;
33 use codemap::{CodeMap, Span};
34 use diagnostic::SpanHandler;
37 use parse::token::{self, InternedString};
39 use std::ascii::AsciiExt;
41 // If you change this list without updating src/doc/reference.md, @cmr will be sad
42 // Don't ever remove anything from this list; set them to 'Removed'.
43 // The version numbers here correspond to the version in which the current status
44 // was set. This is most important for knowing when a particular feature became
46 // NB: The featureck.py script parses this information directly out of the source
47 // so take care when modifying it.
48 const KNOWN_FEATURES: &'static [(&'static str, &'static str, Status)] = &[
49 ("globs", "1.0.0", Accepted),
50 ("macro_rules", "1.0.0", Accepted),
51 ("struct_variant", "1.0.0", Accepted),
52 ("asm", "1.0.0", Active),
53 ("managed_boxes", "1.0.0", Removed),
54 ("non_ascii_idents", "1.0.0", Active),
55 ("thread_local", "1.0.0", Active),
56 ("link_args", "1.0.0", Active),
57 ("plugin_registrar", "1.0.0", Active),
58 ("log_syntax", "1.0.0", Active),
59 ("trace_macros", "1.0.0", Active),
60 ("concat_idents", "1.0.0", Active),
61 ("unsafe_destructor", "1.0.0", Active),
62 ("intrinsics", "1.0.0", Active),
63 ("lang_items", "1.0.0", Active),
65 ("simd", "1.0.0", Active),
66 ("default_type_params", "1.0.0", Accepted),
67 ("quote", "1.0.0", Active),
68 ("link_llvm_intrinsics", "1.0.0", Active),
69 ("linkage", "1.0.0", Active),
70 ("struct_inherit", "1.0.0", Removed),
72 ("quad_precision_float", "1.0.0", Removed),
74 ("rustc_diagnostic_macros", "1.0.0", Active),
75 ("unboxed_closures", "1.0.0", Active),
76 ("reflect", "1.0.0", Active),
77 ("import_shadowing", "1.0.0", Removed),
78 ("advanced_slice_patterns", "1.0.0", Active),
79 ("tuple_indexing", "1.0.0", Accepted),
80 ("associated_types", "1.0.0", Accepted),
81 ("visible_private_types", "1.0.0", Active),
82 ("slicing_syntax", "1.0.0", Accepted),
83 ("box_syntax", "1.0.0", Active),
84 ("on_unimplemented", "1.0.0", Active),
85 ("simd_ffi", "1.0.0", Active),
86 ("allocator", "1.0.0", Active),
88 ("if_let", "1.0.0", Accepted),
89 ("while_let", "1.0.0", Accepted),
91 ("plugin", "1.0.0", Active),
92 ("start", "1.0.0", Active),
93 ("main", "1.0.0", Active),
95 // A temporary feature gate used to enable parser extensions needed
96 // to bootstrap fix for #5723.
97 ("issue_5723_bootstrap", "1.0.0", Accepted),
99 // A way to temporarily opt out of opt in copy. This will *never* be accepted.
100 ("opt_out_copy", "1.0.0", Removed),
102 // A way to temporarily opt out of the new orphan rules. This will *never* be accepted.
103 ("old_orphan_check", "1.0.0", Deprecated),
105 // A way to temporarily opt out of the new impl rules. This will *never* be accepted.
106 ("old_impl_check", "1.0.0", Deprecated),
108 // OIBIT specific features
109 ("optin_builtin_traits", "1.0.0", Active),
111 // macro reexport needs more discussion and stabilization
112 ("macro_reexport", "1.0.0", Active),
114 // These are used to test this portion of the compiler, they don't actually
116 ("test_accepted_feature", "1.0.0", Accepted),
117 ("test_removed_feature", "1.0.0", Removed),
119 // Allows use of #[staged_api]
120 ("staged_api", "1.0.0", Active),
122 // Allows using items which are missing stability attributes
123 ("unmarked_api", "1.0.0", Active),
125 // Allows using #![no_std]
126 ("no_std", "1.0.0", Active),
128 // Allows using `box` in patterns; RFC 469
129 ("box_patterns", "1.0.0", Active),
131 // Allows using the unsafe_no_drop_flag attribute (unlikely to
132 // switch to Accepted; see RFC 320)
133 ("unsafe_no_drop_flag", "1.0.0", Active),
135 // Allows the use of custom attributes; RFC 572
136 ("custom_attribute", "1.0.0", Active),
138 // Allows the use of #[derive(Anything)] as sugar for
139 // #[derive_Anything].
140 ("custom_derive", "1.0.0", Active),
142 // Allows the use of rustc_* attributes; RFC 572
143 ("rustc_attrs", "1.0.0", Active),
145 // Allows the use of `static_assert`
146 ("static_assert", "1.0.0", Active),
148 // Allows the use of #[allow_internal_unstable]. This is an
149 // attribute on macro_rules! and can't use the attribute handling
150 // below (it has to be checked before expansion possibly makes
151 // macros disappear).
152 ("allow_internal_unstable", "1.0.0", Active),
154 // (changing above list without updating src/doc/reference.md makes @cmr sad)
157 /// Represents an active feature that is currently being implemented or
158 /// currently being considered for addition/removal.
161 /// Represents a feature gate that is temporarily enabling deprecated behavior.
162 /// This gate will never be accepted.
165 /// Represents a feature which has since been removed (it was once Active)
168 /// This language feature has since been Accepted (it was once Active)
172 // Attributes that have a special meaning to rustc or rustdoc
173 pub const KNOWN_ATTRIBUTES: &'static [(&'static str, AttributeType)] = &[
181 ("macro_reexport", Normal),
182 ("macro_use", Normal),
183 ("macro_export", Normal),
184 ("plugin_registrar", Normal),
187 ("cfg_attr", Normal),
196 ("unsafe_destructor", Normal),
197 ("automatically_derived", Normal),
198 ("no_mangle", Normal),
201 ("should_panic", Normal),
203 ("no_implicit_prelude", Normal),
204 ("reexport_test_harness_main", Normal),
205 ("link_args", Normal),
206 ("macro_escape", Normal),
209 ("staged_api", Gated("staged_api",
210 "staged_api is for use by rustc only")),
211 ("plugin", Gated("plugin",
212 "compiler plugins are experimental \
213 and possibly buggy")),
214 ("no_std", Gated("no_std",
215 "no_std is experimental")),
216 ("lang", Gated("lang_items",
217 "language items are subject to change")),
218 ("linkage", Gated("linkage",
219 "the `linkage` attribute is experimental \
220 and not portable across platforms")),
221 ("thread_local", Gated("thread_local",
222 "`#[thread_local]` is an experimental feature, and does not \
223 currently handle destructors. There is no corresponding \
224 `#[task_local]` mapping to the task model")),
226 ("rustc_on_unimplemented", Gated("on_unimplemented",
227 "the `#[rustc_on_unimplemented]` attribute \
228 is an experimental feature")),
229 ("allocator", Gated("allocator",
230 "the `#[allocator]` attribute is an experimental feature")),
231 ("rustc_variance", Gated("rustc_attrs",
232 "the `#[rustc_variance]` attribute \
233 is an experimental feature")),
234 ("rustc_error", Gated("rustc_attrs",
235 "the `#[rustc_error]` attribute \
236 is an experimental feature")),
237 ("rustc_move_fragments", Gated("rustc_attrs",
238 "the `#[rustc_move_fragments]` attribute \
239 is an experimental feature")),
241 ("allow_internal_unstable", Gated("allow_internal_unstable",
242 EXPLAIN_ALLOW_INTERNAL_UNSTABLE)),
244 // FIXME: #14408 whitelist docs since rustdoc looks at them
245 ("doc", Whitelisted),
247 // FIXME: #14406 these are processed in trans, which happens after the
249 ("cold", Whitelisted),
250 ("export_name", Whitelisted),
251 ("inline", Whitelisted),
252 ("link", Whitelisted),
253 ("link_name", Whitelisted),
254 ("link_section", Whitelisted),
255 ("no_builtins", Whitelisted),
256 ("no_mangle", Whitelisted),
257 ("no_stack_check", Whitelisted),
258 ("packed", Whitelisted),
259 ("static_assert", Gated("static_assert",
260 "`#[static_assert]` is an experimental feature, and has a poor API")),
261 ("no_debug", Whitelisted),
262 ("omit_gdb_pretty_printer_section", Whitelisted),
263 ("unsafe_no_drop_flag", Gated("unsafe_no_drop_flag",
264 "unsafe_no_drop_flag has unstable semantics \
265 and may be removed in the future")),
268 ("prelude_import", Whitelisted),
270 // FIXME: #14407 these are only looked at on-demand so we can't
271 // guarantee they'll have already been checked
272 ("deprecated", Whitelisted),
273 ("must_use", Whitelisted),
274 ("stable", Whitelisted),
275 ("unstable", Whitelisted),
277 // FIXME: #19470 this shouldn't be needed forever
278 ("old_orphan_check", Whitelisted),
279 ("old_impl_check", Whitelisted),
281 ("rustc_paren_sugar", Gated("unboxed_closures",
282 "unboxed_closures are still evolving")),
283 ("rustc_reflect_like", Gated("reflect",
284 "defining reflective traits is still evolving")),
286 // Crate level attributes
287 ("crate_name", CrateLevel),
288 ("crate_type", CrateLevel),
289 ("crate_id", CrateLevel),
290 ("feature", CrateLevel),
291 ("no_start", CrateLevel),
292 ("no_main", CrateLevel),
293 ("no_builtins", CrateLevel),
294 ("recursion_limit", CrateLevel),
297 #[derive(PartialEq, Copy, Debug)]
298 pub enum AttributeType {
299 /// Normal, builtin attribute that is consumed
300 /// by the compiler before the unused_attribute check
303 /// Builtin attribute that may not be consumed by the compiler
304 /// before the unused_attribute check. These attributes
305 /// will be ignored by the unused_attribute lint
308 /// Is gated by a given feature gate and reason
309 /// These get whitelisted too
310 Gated(&'static str, &'static str),
312 /// Builtin attribute that is only allowed at the crate level
316 /// A set of features to be used by later passes.
317 pub struct Features {
318 pub unboxed_closures: bool,
319 pub rustc_diagnostic_macros: bool,
320 pub visible_private_types: bool,
321 pub allow_quote: bool,
323 pub allow_log_syntax: bool,
324 pub allow_concat_idents: bool,
325 pub allow_trace_macros: bool,
326 pub allow_internal_unstable: bool,
327 pub allow_custom_derive: bool,
328 pub old_orphan_check: bool,
330 pub unmarked_api: bool,
331 /// spans of #![feature] attrs for stable language features. for error reporting
332 pub declared_stable_lang_features: Vec<Span>,
333 /// #![feature] attrs for non-language (library) features
334 pub declared_lib_features: Vec<(InternedString, Span)>
338 pub fn new() -> Features {
340 unboxed_closures: false,
341 rustc_diagnostic_macros: false,
342 visible_private_types: false,
345 allow_log_syntax: false,
346 allow_concat_idents: false,
347 allow_trace_macros: false,
348 allow_internal_unstable: false,
349 allow_custom_derive: false,
350 old_orphan_check: false,
353 declared_stable_lang_features: Vec::new(),
354 declared_lib_features: Vec::new()
360 features: Vec<&'static str>,
361 span_handler: &'a SpanHandler,
365 impl<'a> Context<'a> {
366 fn gate_feature(&self, feature: &str, span: Span, explain: &str) {
367 let has_feature = self.has_feature(feature);
368 debug!("gate_feature(feature = {:?}, span = {:?}); has? {}", feature, span, has_feature);
370 emit_feature_err(self.span_handler, feature, span, explain);
373 fn has_feature(&self, feature: &str) -> bool {
374 self.features.iter().any(|&n| n == feature)
377 fn check_attribute(&self, attr: &ast::Attribute) {
378 debug!("check_attribute(attr = {:?})", attr);
379 let name = &*attr.name();
380 for &(n, ty) in KNOWN_ATTRIBUTES {
382 if let Gated(gate, desc) = ty {
383 self.gate_feature(gate, attr.span, desc);
385 debug!("check_attribute: {:?} is known, {:?}", name, ty);
389 if name.starts_with("rustc_") {
390 self.gate_feature("rustc_attrs", attr.span,
391 "unless otherwise specified, attributes \
392 with the prefix `rustc_` \
393 are reserved for internal compiler diagnostics");
394 } else if name.starts_with("derive_") {
395 self.gate_feature("custom_derive", attr.span,
396 "attributes of the form `#[derive_*]` are reserved
399 self.gate_feature("custom_attribute", attr.span,
400 &format!("The attribute `{}` is currently \
401 unknown to the the compiler and \
403 added to it in the future",
409 pub fn emit_feature_err(diag: &SpanHandler, feature: &str, span: Span, explain: &str) {
410 diag.span_err(span, explain);
411 diag.fileline_help(span, &format!("add #![feature({})] to the \
412 crate attributes to enable",
416 pub fn emit_feature_warn(diag: &SpanHandler, feature: &str, span: Span, explain: &str) {
417 diag.span_warn(span, explain);
418 if diag.handler.can_emit_warnings {
419 diag.fileline_help(span, &format!("add #![feature({})] to the \
420 crate attributes to silence this warning",
425 pub const EXPLAIN_ASM: &'static str =
426 "inline assembly is not stable enough for use and is subject to change";
428 pub const EXPLAIN_LOG_SYNTAX: &'static str =
429 "`log_syntax!` is not stable enough for use and is subject to change";
431 pub const EXPLAIN_CONCAT_IDENTS: &'static str =
432 "`concat_idents` is not stable enough for use and is subject to change";
434 pub const EXPLAIN_TRACE_MACROS: &'static str =
435 "`trace_macros` is not stable enough for use and is subject to change";
436 pub const EXPLAIN_ALLOW_INTERNAL_UNSTABLE: &'static str =
437 "allow_internal_unstable side-steps feature gating and stability checks";
439 pub const EXPLAIN_CUSTOM_DERIVE: &'static str =
440 "`#[derive]` for custom traits is not stable enough for use and is subject to change";
442 struct MacroVisitor<'a> {
443 context: &'a Context<'a>
446 impl<'a, 'v> Visitor<'v> for MacroVisitor<'a> {
447 fn visit_mac(&mut self, mac: &ast::Mac) {
448 let ast::MacInvocTT(ref path, _, _) = mac.node;
449 let id = path.segments.last().unwrap().identifier;
451 // Issue 22234: If you add a new case here, make sure to also
452 // add code to catch the macro during or after expansion.
454 // We still keep this MacroVisitor (rather than *solely*
455 // relying on catching cases during or after expansion) to
456 // catch uses of these macros within conditionally-compiled
457 // code, e.g. `#[cfg]`-guarded functions.
459 if id == token::str_to_ident("asm") {
460 self.context.gate_feature("asm", path.span, EXPLAIN_ASM);
463 else if id == token::str_to_ident("log_syntax") {
464 self.context.gate_feature("log_syntax", path.span, EXPLAIN_LOG_SYNTAX);
467 else if id == token::str_to_ident("trace_macros") {
468 self.context.gate_feature("trace_macros", path.span, EXPLAIN_TRACE_MACROS);
471 else if id == token::str_to_ident("concat_idents") {
472 self.context.gate_feature("concat_idents", path.span, EXPLAIN_CONCAT_IDENTS);
476 fn visit_attribute(&mut self, attr: &'v ast::Attribute) {
477 self.context.check_attribute(attr);
481 struct PostExpansionVisitor<'a> {
482 context: &'a Context<'a>
485 impl<'a> PostExpansionVisitor<'a> {
486 fn gate_feature(&self, feature: &str, span: Span, explain: &str) {
487 if !self.context.cm.span_allows_unstable(span) {
488 self.context.gate_feature(feature, span, explain)
493 impl<'a, 'v> Visitor<'v> for PostExpansionVisitor<'a> {
494 fn visit_attribute(&mut self, attr: &ast::Attribute) {
495 if !self.context.cm.span_allows_unstable(attr.span) {
496 self.context.check_attribute(attr);
500 fn visit_name(&mut self, sp: Span, name: ast::Name) {
501 if !token::get_name(name).is_ascii() {
502 self.gate_feature("non_ascii_idents", sp,
503 "non-ascii idents are not fully supported.");
507 fn visit_item(&mut self, i: &ast::Item) {
509 ast::ItemExternCrate(_) => {
510 if attr::contains_name(&i.attrs[..], "macro_reexport") {
511 self.gate_feature("macro_reexport", i.span,
512 "macros reexports are experimental \
513 and possibly buggy");
517 ast::ItemForeignMod(ref foreign_module) => {
518 if attr::contains_name(&i.attrs[..], "link_args") {
519 self.gate_feature("link_args", i.span,
520 "the `link_args` attribute is not portable \
521 across platforms, it is recommended to \
522 use `#[link(name = \"foo\")]` instead")
524 if foreign_module.abi == RustIntrinsic {
525 self.gate_feature("intrinsics",
527 "intrinsics are subject to change")
532 if attr::contains_name(&i.attrs[..], "plugin_registrar") {
533 self.gate_feature("plugin_registrar", i.span,
534 "compiler plugins are experimental and possibly buggy");
536 if attr::contains_name(&i.attrs[..], "start") {
537 self.gate_feature("start", i.span,
538 "a #[start] function is an experimental \
539 feature whose signature may change \
542 if attr::contains_name(&i.attrs[..], "main") {
543 self.gate_feature("main", i.span,
544 "declaration of a nonstandard #[main] \
545 function may change over time, for now \
546 a top-level `fn main()` is required");
550 ast::ItemStruct(..) => {
551 if attr::contains_name(&i.attrs[..], "simd") {
552 self.gate_feature("simd", i.span,
553 "SIMD types are experimental and possibly buggy");
557 ast::ItemDefaultImpl(..) => {
558 self.gate_feature("optin_builtin_traits",
560 "default trait implementations are experimental \
561 and possibly buggy");
564 ast::ItemImpl(_, polarity, _, _, _, _) => {
566 ast::ImplPolarity::Negative => {
567 self.gate_feature("optin_builtin_traits",
569 "negative trait bounds are not yet fully implemented; \
570 use marker types for now");
575 if attr::contains_name(&i.attrs,
576 "unsafe_destructor") {
577 self.gate_feature("unsafe_destructor",
579 "`#[unsafe_destructor]` allows too \
580 many unsafe patterns and may be \
581 removed in the future");
584 if attr::contains_name(&i.attrs[..],
585 "old_orphan_check") {
589 "the new orphan check rules will eventually be strictly enforced");
592 if attr::contains_name(&i.attrs[..],
594 self.gate_feature("old_impl_check",
596 "`#[old_impl_check]` will be removed in the future");
603 visit::walk_item(self, i);
606 fn visit_foreign_item(&mut self, i: &ast::ForeignItem) {
607 let links_to_llvm = match attr::first_attr_value_str_by_name(&i.attrs,
609 Some(val) => val.starts_with("llvm."),
613 self.gate_feature("link_llvm_intrinsics", i.span,
614 "linking to LLVM intrinsics is experimental");
617 visit::walk_foreign_item(self, i)
620 fn visit_expr(&mut self, e: &ast::Expr) {
622 ast::ExprBox(..) | ast::ExprUnary(ast::UnOp::UnUniq, _) => {
623 self.gate_feature("box_syntax",
625 "box expression syntax is experimental; \
626 you can call `Box::new` instead.");
630 visit::walk_expr(self, e);
633 fn visit_pat(&mut self, pattern: &ast::Pat) {
635 ast::PatVec(_, Some(_), ref last) if !last.is_empty() => {
636 self.gate_feature("advanced_slice_patterns",
638 "multiple-element slice matches anywhere \
639 but at the end of a slice (e.g. \
640 `[0, ..xs, 0]` are experimental")
643 self.gate_feature("box_patterns",
645 "box pattern syntax is experimental");
649 visit::walk_pat(self, pattern)
652 fn visit_fn(&mut self,
653 fn_kind: visit::FnKind<'v>,
654 fn_decl: &'v ast::FnDecl,
655 block: &'v ast::Block,
659 visit::FkItemFn(_, _, _, abi) if abi == RustIntrinsic => {
660 self.gate_feature("intrinsics",
662 "intrinsics are subject to change")
666 visit::walk_fn(self, fn_kind, fn_decl, block, span);
670 fn check_crate_inner<F>(cm: &CodeMap, span_handler: &SpanHandler,
674 where F: FnOnce(&mut Context, &ast::Crate)
676 let mut cx = Context {
677 features: Vec::new(),
678 span_handler: span_handler,
682 let mut accepted_features = Vec::new();
683 let mut unknown_features = Vec::new();
685 for attr in &krate.attrs {
686 if !attr.check_name("feature") {
690 match attr.meta_item_list() {
692 span_handler.span_err(attr.span, "malformed feature attribute, \
693 expected #![feature(...)]");
697 let name = match mi.node {
698 ast::MetaWord(ref word) => (*word).clone(),
700 span_handler.span_err(mi.span,
701 "malformed feature, expected just \
706 match KNOWN_FEATURES.iter()
707 .find(|& &(n, _, _)| name == n) {
708 Some(&(name, _, Active)) => {
709 cx.features.push(name);
711 Some(&(name, _, Deprecated)) => {
712 cx.features.push(name);
713 span_handler.span_warn(
715 "feature is deprecated and will only be available \
716 for a limited time, please rewrite code that relies on it");
718 Some(&(_, _, Removed)) => {
719 span_handler.span_err(mi.span, "feature has been removed");
721 Some(&(_, _, Accepted)) => {
722 accepted_features.push(mi.span);
725 unknown_features.push((name, mi.span));
733 check(&mut cx, krate);
735 // FIXME (pnkfelix): Before adding the 99th entry below, change it
736 // to a single-pass (instead of N calls to `.has_feature`).
739 unboxed_closures: cx.has_feature("unboxed_closures"),
740 rustc_diagnostic_macros: cx.has_feature("rustc_diagnostic_macros"),
741 visible_private_types: cx.has_feature("visible_private_types"),
742 allow_quote: cx.has_feature("quote"),
743 allow_asm: cx.has_feature("asm"),
744 allow_log_syntax: cx.has_feature("log_syntax"),
745 allow_concat_idents: cx.has_feature("concat_idents"),
746 allow_trace_macros: cx.has_feature("trace_macros"),
747 allow_internal_unstable: cx.has_feature("allow_internal_unstable"),
748 allow_custom_derive: cx.has_feature("custom_derive"),
749 old_orphan_check: cx.has_feature("old_orphan_check"),
750 simd_ffi: cx.has_feature("simd_ffi"),
751 unmarked_api: cx.has_feature("unmarked_api"),
752 declared_stable_lang_features: accepted_features,
753 declared_lib_features: unknown_features
757 pub fn check_crate_macros(cm: &CodeMap, span_handler: &SpanHandler, krate: &ast::Crate)
759 check_crate_inner(cm, span_handler, krate,
760 |ctx, krate| visit::walk_crate(&mut MacroVisitor { context: ctx }, krate))
763 pub fn check_crate(cm: &CodeMap, span_handler: &SpanHandler, krate: &ast::Crate)
766 check_crate_inner(cm, span_handler, krate,
767 |ctx, krate| visit::walk_crate(&mut PostExpansionVisitor { context: ctx },