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