src/doc/reference/src/attributes.md

   1 {{#include attributes-redirect.html}}
   2 # Attributes
   3
   4 > **<sup>Syntax</sup>**\
   5 > _InnerAttribute_ :\
   6 > &nbsp;&nbsp; `#` `!` `[` _Attr_ `]`
   7 >
   8 > _OuterAttribute_ :\
   9 > &nbsp;&nbsp; `#` `[` _Attr_ `]`
  10 >
  11 > _Attr_ :\
  12 > &nbsp;&nbsp; [_SimplePath_] _AttrInput_<sup>?</sup>
  13 >
  14 > _AttrInput_ :\
  15 > &nbsp;&nbsp; &nbsp;&nbsp; [_DelimTokenTree_]\
  16 > &nbsp;&nbsp; | `=` [_LiteralExpression_]<sub>_without suffix_</sub>
  17
  18 An _attribute_ is a general, free-form metadatum that is interpreted according
  19 to name, convention, and language and compiler version. Attributes are modeled
  20 on Attributes in [ECMA-335], with the syntax coming from [ECMA-334] \(C#).
  21
  22 _Inner attributes_, written with a bang (`!`) after the hash (`#`), apply to the
  23 item that the attribute is declared within. _Outer attributes_, written without
  24 the bang after the hash, apply to the thing that follows the attribute.
  25
  26 The attribute consists of a path to the attribute, followed by an optional
  27 delimited token tree whose interpretation is defined by the attribute.
  28 Attributes other than macro attributes also allow the input to be an equals
  29 sign (`=`) followed by a literal expression. See the [meta item
  30 syntax](#meta-item-attribute-syntax) below for more details.
  31
  32 Attributes can be classified into the following kinds:
  33
  34 * [Built-in attributes]
  35 * [Macro attributes][attribute macros]
  36 * [Derive macro helper attributes]
  37 * [Tool attributes](#tool-attributes)
  38
  39 Attributes may be applied to many things in the language:
  40
  41 * All [item declarations] accept outer attributes while [external blocks],
  42   [functions], [implementations], and [modules] accept inner attributes.
  43 * Most [statements] accept outer attributes (see [Expression Attributes] for
  44   limitations on expression statements).
  45 * [Block expressions] accept outer and inner attributes, but only when they are
  46   the outer expression of an [expression statement] or the final expression of
  47   another block expression.
  48 * [Enum] variants and [struct] and [union] fields accept outer attributes.
  49 * [Match expression arms][match expressions] accept outer attributes.
  50 * [Generic lifetime or type parameter][generics] accept outer attributes.
  51 * Expressions accept outer attributes in limited situations, see [Expression
  52   Attributes] for details.
  53
  54 Some examples of attributes:
  55
  56 ```rust
  57 // General metadata applied to the enclosing module or crate.
  58 #![crate_type = "lib"]
  59
  60 // A function marked as a unit test
  61 #[test]
  62 fn test_foo() {
  63     /* ... */
  64 }
  65
  66 // A conditionally-compiled module
  67 #[cfg(target_os = "linux")]
  68 mod bar {
  69     /* ... */
  70 }
  71
  72 // A lint attribute used to suppress a warning/error
  73 #[allow(non_camel_case_types)]
  74 type int8_t = i8;
  75
  76 // Inner attribute applies to the entire function.
  77 fn some_unused_variables() {
  78   #![allow(unused_variables)]
  79
  80   let x = ();
  81   let y = ();
  82   let z = ();
  83 }
  84 ```
  85
  86 ## Meta Item Attribute Syntax
  87
  88 A "meta item" is the syntax used for the _Attr_ rule by most [built-in
  89 attributes] and the [`meta` macro fragment specifier]. It has the following
  90 grammar:
  91
  92 > **<sup>Syntax</sup>**\
  93 > _MetaItem_ :\
  94 > &nbsp;&nbsp; &nbsp;&nbsp; [_SimplePath_]\
  95 > &nbsp;&nbsp; | [_SimplePath_] `=` [_LiteralExpression_]<sub>_without suffix_</sub>\
  96 > &nbsp;&nbsp; | [_SimplePath_] `(` _MetaSeq_<sup>?</sup> `)`
  97 >
  98 > _MetaSeq_ :\
  99 > &nbsp;&nbsp; _MetaItemInner_ ( `,` MetaItemInner )<sup>\*</sup> `,`<sup>?</sup>
 100 >
 101 > _MetaItemInner_ :\
 102 > &nbsp;&nbsp; &nbsp;&nbsp; _MetaItem_\
 103 > &nbsp;&nbsp; | [_LiteralExpression_]<sub>_without suffix_</sub>
 104
 105 Literal expressions in meta items must not include integer or float type
 106 suffixes.
 107
 108 Various built-in attributes use different subsets of the meta item syntax to
 109 specify their inputs. The following grammar rules show some commonly used
 110 forms:
 111
 112 > **<sup>Syntax</sup>**\
 113 > _MetaWord_:\
 114 > &nbsp;&nbsp; [IDENTIFIER]
 115 >
 116 > _MetaNameValueStr_:\
 117 > &nbsp;&nbsp; [IDENTIFIER] `=` ([STRING_LITERAL] | [RAW_STRING_LITERAL])
 118 >
 119 > _MetaListPaths_:\
 120 > &nbsp;&nbsp; [IDENTIFIER] `(` ( [_SimplePath_] (`,` [_SimplePath_])* `,`<sup>?</sup> )<sup>?</sup> `)`
 121 >
 122 > _MetaListIdents_:\
 123 > &nbsp;&nbsp; [IDENTIFIER] `(` ( [IDENTIFIER] (`,` [IDENTIFIER])* `,`<sup>?</sup> )<sup>?</sup> `)`
 124 >
 125 > _MetaListNameValueStr_:\
 126 > &nbsp;&nbsp; [IDENTIFIER] `(` ( _MetaNameValueStr_ (`,` _MetaNameValueStr_)* `,`<sup>?</sup> )<sup>?</sup> `)`
 127
 128 Some examples of meta items are:
 129
 130 Style | Example
 131 ------|--------
 132 _MetaWord_ | `no_std`
 133 _MetaNameValueStr_ | `doc = "example"`
 134 _MetaListPaths_ | `allow(unused, clippy::inline_always)`
 135 _MetaListIdents_ | `macro_use(foo, bar)`
 136 _MetaListNameValueStr_ | `link(name = "CoreFoundation", kind = "framework")`
 137
 138 ## Active and inert attributes
 139
 140 An attribute is either active or inert. During attribute processing, *active
 141 attributes* remove themselves from the thing they are on while *inert attributes*
 142 stay on.
 143
 144 The [`cfg`] and [`cfg_attr`] attributes are active. The [`test`] attribute is
 145 inert when compiling for tests and active otherwise. [Attribute macros] are
 146 active. All other attributes are inert.
 147
 148 ## Tool attributes
 149
 150 The compiler may allow attributes for external tools where each tool resides
 151 in its own namespace. The first segment of the attribute path is the name of
 152 the tool, with one or more additional segments whose interpretation is up to
 153 the tool.
 154
 155 When a tool is not in use, the tool's attributes are accepted without a
 156 warning. When the tool is in use, the tool is responsible for processing and
 157 interpretation of its attributes.
 158
 159 Tool attributes are not available if the [`no_implicit_prelude`] attribute is
 160 used.
 161
 162 ```rust
 163 // Tells the rustfmt tool to not format the following element.
 164 #[rustfmt::skip]
 165 struct S {
 166 }
 167
 168 // Controls the "cyclomatic complexity" threshold for the clippy tool.
 169 #[clippy::cyclomatic_complexity = "100"]
 170 pub fn f() {}
 171 ```
 172
 173 > Note: `rustc` currently recognizes the tools "clippy" and "rustfmt".
 174
 175 ## Built-in attributes index
 176
 177 The following is an index of all built-in attributes.
 178
 179 - Conditional compilation
 180   - [`cfg`] — Controls conditional compilation.
 181   - [`cfg_attr`] — Conditionally includes attributes.
 182 - Testing
 183   - [`test`] — Marks a function as a test.
 184   - [`ignore`] — Disables a test function.
 185   - [`should_panic`] — Indicates a test should generate a panic.
 186 - Derive
 187   - [`derive`] — Automatic trait implementations.
 188 - Macros
 189   - [`macro_export`] — Exports a `macro_rules` macro for cross-crate usage.
 190   - [`macro_use`] — Expands macro visibility, or imports macros from other
 191     crates.
 192   - [`proc_macro`] — Defines a function-like macro.
 193   - [`proc_macro_derive`] — Defines a derive macro.
 194   - [`proc_macro_attribute`] — Defines an attribute macro.
 195 - Diagnostics
 196   - [`allow`], [`warn`], [`deny`], [`forbid`] — Alters the default lint level.
 197   - [`deprecated`] — Generates deprecation notices.
 198   - [`must_use`] — Generates a lint for unused values.
 199 - ABI, linking, symbols, and FFI
 200   - [`link`] — Specifies a native library to link with an `extern` block.
 201   - [`link_name`] — Specifies the name of the symbol for functions or statics
 202     in an `extern` block.
 203   - [`no_link`] — Prevents linking an extern crate.
 204   - [`repr`] — Controls type layout.
 205   - [`crate_type`] — Specifies the type of crate (library, executable, etc.).
 206   - [`no_main`] — Disables emitting the `main` symbol.
 207   - [`export_name`] — Specifies the exported symbol name for a function or
 208     static.
 209   - [`link_section`] — Specifies the section of an object file to use for a
 210     function or static.
 211   - [`no_mangle`] — Disables symbol name encoding.
 212   - [`used`] — Forces the compiler to keep a static item in the output
 213     object file.
 214   - [`crate_name`] — Specifies the crate name.
 215 - Code generation
 216   - [`inline`] — Hint to inline code.
 217   - [`cold`] — Hint that a function is unlikely to be called.
 218   - [`no_builtins`] — Disables use of certain built-in functions.
 219   - [`target_feature`] — Configure platform-specific code generation.
 220 - Documentation
 221   - `doc` — Specifies documentation. See [The Rustdoc Book] for more
 222     information. [Doc comments] are transformed into `doc` attributes.
 223 - Preludes
 224   - [`no_std`] — Removes std from the prelude.
 225   - [`no_implicit_prelude`] — Disables prelude lookups within a module.
 226 - Modules
 227   - [`path`] — Specifies the filename for a module.
 228 - Limits
 229   - [`recursion_limit`] — Sets the maximum recursion limit for certain
 230     compile-time operations.
 231   - [`type_length_limit`] — Sets the maximum size of a polymorphic type.
 232 - Runtime
 233   - [`panic_handler`] — Sets the function to handle panics.
 234   - [`global_allocator`] — Sets the global memory allocator.
 235   - [`windows_subsystem`] — Specifies the windows subsystem to link with.
 236 - Features
 237   - `feature` — Used to enable unstable or experimental compiler features. See
 238     [The Unstable Book] for features implemented in `rustc`.
 239
 240 [Doc comments]: comments.html#doc-comments
 241 [ECMA-334]: https://www.ecma-international.org/publications/standards/Ecma-334.htm
 242 [ECMA-335]: https://www.ecma-international.org/publications/standards/Ecma-335.htm
 243 [Expression Attributes]: expressions.html#expression-attributes
 244 [IDENTIFIER]: identifiers.html
 245 [RAW_STRING_LITERAL]: tokens.html#raw-string-literals
 246 [STRING_LITERAL]: tokens.html#string-literals
 247 [The Rustdoc Book]: ../rustdoc/the-doc-attribute.html
 248 [The Unstable Book]: ../unstable-book/index.html
 249 [_DelimTokenTree_]: macros.html
 250 [_LiteralExpression_]: expressions/literal-expr.html
 251 [_SimplePath_]: paths.html#simple-paths
 252 [`allow`]: attributes/diagnostics.html#lint-check-attributes
 253 [`cfg_attr`]: conditional-compilation.html#the-cfg_attr-attribute
 254 [`cfg`]: conditional-compilation.html#the-cfg-attribute
 255 [`cold`]: attributes/codegen.html#the-cold-attribute
 256 [`crate_name`]: crates-and-source-files.html#the-crate_name-attribute
 257 [`crate_type`]: linkage.html
 258 [`deny`]: attributes/diagnostics.html#lint-check-attributes
 259 [`deprecated`]: attributes/diagnostics.html#the-deprecated-attribute
 260 [`derive`]: attributes/derive.html
 261 [`export_name`]: abi.html#the-export_name-attribute
 262 [`forbid`]: attributes/diagnostics.html#lint-check-attributes
 263 [`global_allocator`]: runtime.html#the-global_allocator-attribute
 264 [`ignore`]: attributes/testing.html#the-ignore-attribute
 265 [`inline`]: attributes/codegen.html#the-inline-attribute
 266 [`link_name`]: items/external-blocks.html#the-link_name-attribute
 267 [`link_section`]: abi.html#the-link_section-attribute
 268 [`link`]: items/external-blocks.html#the-link-attribute
 269 [`macro_export`]: macros-by-example.html#path-based-scope
 270 [`macro_use`]: macros-by-example.html#the-macro_use-attribute
 271 [`meta` macro fragment specifier]: macros-by-example.html
 272 [`must_use`]: attributes/diagnostics.html#the-must_use-attribute
 273 [`no_builtins`]: attributes/codegen.html#the-no_builtins-attribute
 274 [`no_implicit_prelude`]: items/modules.html#prelude-items
 275 [`no_link`]: items/extern-crates.html#the-no_link-attribute
 276 [`no_main`]: crates-and-source-files.html#the-no_main-attribute
 277 [`no_mangle`]: abi.html#the-no_mangle-attribute
 278 [`no_std`]: crates-and-source-files.html#preludes-and-no_std
 279 [`panic_handler`]: runtime.html#the-panic_handler-attribute
 280 [`path`]: items/modules.html#the-path-attribute
 281 [`proc_macro_attribute`]: procedural-macros.html#attribute-macros
 282 [`proc_macro_derive`]: procedural-macros.html#derive-macros
 283 [`proc_macro`]: procedural-macros.html#function-like-procedural-macros
 284 [`recursion_limit`]: attributes/limits.html#the-recursion_limit-attribute
 285 [`repr`]: type-layout.html#representations
 286 [`should_panic`]: attributes/testing.html#the-should_panic-attribute
 287 [`target_feature`]: attributes/codegen.html#the-target_feature-attribute
 288 [`test`]: attributes/testing.html#the-test-attribute
 289 [`type_length_limit`]: attributes/limits.html#the-type_length_limit-attribute
 290 [`used`]: abi.html#the-used-attribute
 291 [`warn`]: attributes/diagnostics.html#lint-check-attributes
 292 [`windows_subsystem`]: runtime.html#the-windows_subsystem-attribute
 293 [attribute macros]: procedural-macros.html#attribute-macros
 294 [block expressions]: expressions/block-expr.html
 295 [built-in attributes]: #built-in-attributes-index
 296 [derive macro helper attributes]: procedural-macros.html#derive-macro-helper-attributes
 297 [enum]: items/enumerations.html
 298 [expression statement]: statements.html#expression-statements
 299 [external blocks]: items/external-blocks.html
 300 [functions]: items/functions.html
 301 [generics]: items/generics.html
 302 [implementations]: items/implementations.html
 303 [item declarations]: items.html
 304 [match expressions]: expressions/match-expr.html
 305 [modules]: items/modules.html
 306 [statements]: statements.html
 307 [struct]: items/structs.html
 308 [union]: items/unions.html