]>
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_]\ | |
17df50a5 | 16 | > | `=` [_Expression_] |
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 | |
17df50a5 | 29 | sign (`=`) followed by an expression. See the [meta item |
532ac7d7 | 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. | |
74b04a01 | 53 | * [Function][functions], [closure] and [function pointer] |
e74abb32 XL |
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_]\ | |
17df50a5 | 97 | > | [_SimplePath_] `=` [_Expression_]\ |
532ac7d7 XL |
98 | > | [_SimplePath_] `(` _MetaSeq_<sup>?</sup> `)` |
99 | > | |
100 | > _MetaSeq_ :\ | |
101 | > _MetaItemInner_ ( `,` MetaItemInner )<sup>\*</sup> `,`<sup>?</sup> | |
102 | > | |
103 | > _MetaItemInner_ :\ | |
104 | > _MetaItem_\ | |
17df50a5 XL |
105 | > | [_Expression_] |
106 | ||
107 | Expressions in meta items must macro-expand to literal expressions, which must not | |
108 | include integer or float type suffixes. Expressions which are not literal expressions | |
109 | will be syntactically accepted (and can be passed to proc-macros), but will be rejected after parsing. | |
110 | ||
111 | Note that if the attribute appears within another macro, it will be expanded | |
112 | after that outer macro. For example, the following code will expand the | |
113 | `Serialize` proc-macro first, which must preserve the `include_str!` call in | |
114 | order for it to be expanded: | |
115 | ||
116 | ```rust ignore | |
117 | #[derive(Serialize)] | |
118 | struct Foo { | |
119 | #[doc = include_str!("x.md")] | |
120 | x: u32 | |
121 | } | |
122 | ``` | |
83c7162d | 123 | |
17df50a5 XL |
124 | Additionally, macros in attributes will be expanded only after all other attributes applied to the item: |
125 | ||
126 | ```rust ignore | |
127 | #[macro_attr1] // expanded first | |
128 | #[doc = mac!()] // `mac!` is expanded fourth. | |
129 | #[macro_attr2] // expanded second | |
130 | #[derive(MacroDerive1, MacroDerive2)] // expanded third | |
131 | fn foo() {} | |
132 | ``` | |
83c7162d | 133 | |
532ac7d7 XL |
134 | Various built-in attributes use different subsets of the meta item syntax to |
135 | specify their inputs. The following grammar rules show some commonly used | |
136 | forms: | |
83c7162d | 137 | |
532ac7d7 XL |
138 | > **<sup>Syntax</sup>**\ |
139 | > _MetaWord_:\ | |
140 | > [IDENTIFIER] | |
83c7162d | 141 | > |
532ac7d7 XL |
142 | > _MetaNameValueStr_:\ |
143 | > [IDENTIFIER] `=` ([STRING_LITERAL] | [RAW_STRING_LITERAL]) | |
83c7162d | 144 | > |
532ac7d7 XL |
145 | > _MetaListPaths_:\ |
146 | > [IDENTIFIER] `(` ( [_SimplePath_] (`,` [_SimplePath_])* `,`<sup>?</sup> )<sup>?</sup> `)` | |
83c7162d | 147 | > |
532ac7d7 XL |
148 | > _MetaListIdents_:\ |
149 | > [IDENTIFIER] `(` ( [IDENTIFIER] (`,` [IDENTIFIER])* `,`<sup>?</sup> )<sup>?</sup> `)` | |
83c7162d | 150 | > |
532ac7d7 XL |
151 | > _MetaListNameValueStr_:\ |
152 | > [IDENTIFIER] `(` ( _MetaNameValueStr_ (`,` _MetaNameValueStr_)* `,`<sup>?</sup> )<sup>?</sup> `)` | |
9fa01778 | 153 | |
532ac7d7 | 154 | Some examples of meta items are: |
8bb4bdeb | 155 | |
532ac7d7 XL |
156 | Style | Example |
157 | ------|-------- | |
158 | _MetaWord_ | `no_std` | |
159 | _MetaNameValueStr_ | `doc = "example"` | |
160 | _MetaListPaths_ | `allow(unused, clippy::inline_always)` | |
161 | _MetaListIdents_ | `macro_use(foo, bar)` | |
162 | _MetaListNameValueStr_ | `link(name = "CoreFoundation", kind = "framework")` | |
8bb4bdeb | 163 | |
532ac7d7 | 164 | ## Active and inert attributes |
8bb4bdeb | 165 | |
532ac7d7 XL |
166 | An attribute is either active or inert. During attribute processing, *active |
167 | attributes* remove themselves from the thing they are on while *inert attributes* | |
168 | stay on. | |
8bb4bdeb | 169 | |
532ac7d7 XL |
170 | The [`cfg`] and [`cfg_attr`] attributes are active. The [`test`] attribute is |
171 | inert when compiling for tests and active otherwise. [Attribute macros] are | |
172 | active. All other attributes are inert. | |
8bb4bdeb | 173 | |
532ac7d7 | 174 | ## Tool attributes |
b7449926 | 175 | |
532ac7d7 | 176 | The compiler may allow attributes for external tools where each tool resides |
5869c6ff XL |
177 | in its own namespace in the [tool prelude]. The first segment of the attribute |
178 | path is the name of the tool, with one or more additional segments whose | |
179 | interpretation is up to the tool. | |
b7449926 | 180 | |
532ac7d7 XL |
181 | When a tool is not in use, the tool's attributes are accepted without a |
182 | warning. When the tool is in use, the tool is responsible for processing and | |
183 | interpretation of its attributes. | |
8bb4bdeb | 184 | |
532ac7d7 XL |
185 | Tool attributes are not available if the [`no_implicit_prelude`] attribute is |
186 | used. | |
8bb4bdeb | 187 | |
cc61c64b | 188 | ```rust |
532ac7d7 XL |
189 | // Tells the rustfmt tool to not format the following element. |
190 | #[rustfmt::skip] | |
191 | struct S { | |
8bb4bdeb | 192 | } |
8bb4bdeb | 193 | |
532ac7d7 XL |
194 | // Controls the "cyclomatic complexity" threshold for the clippy tool. |
195 | #[clippy::cyclomatic_complexity = "100"] | |
196 | pub fn f() {} | |
8bb4bdeb XL |
197 | ``` |
198 | ||
532ac7d7 XL |
199 | > Note: `rustc` currently recognizes the tools "clippy" and "rustfmt". |
200 | ||
201 | ## Built-in attributes index | |
202 | ||
203 | The following is an index of all built-in attributes. | |
204 | ||
205 | - Conditional compilation | |
206 | - [`cfg`] — Controls conditional compilation. | |
207 | - [`cfg_attr`] — Conditionally includes attributes. | |
208 | - Testing | |
209 | - [`test`] — Marks a function as a test. | |
210 | - [`ignore`] — Disables a test function. | |
211 | - [`should_panic`] — Indicates a test should generate a panic. | |
212 | - Derive | |
213 | - [`derive`] — Automatic trait implementations. | |
ba9703b0 XL |
214 | - [`automatically_derived`] — Marker for implementations created by |
215 | `derive`. | |
532ac7d7 XL |
216 | - Macros |
217 | - [`macro_export`] — Exports a `macro_rules` macro for cross-crate usage. | |
218 | - [`macro_use`] — Expands macro visibility, or imports macros from other | |
219 | crates. | |
220 | - [`proc_macro`] — Defines a function-like macro. | |
221 | - [`proc_macro_derive`] — Defines a derive macro. | |
222 | - [`proc_macro_attribute`] — Defines an attribute macro. | |
223 | - Diagnostics | |
224 | - [`allow`], [`warn`], [`deny`], [`forbid`] — Alters the default lint level. | |
225 | - [`deprecated`] — Generates deprecation notices. | |
226 | - [`must_use`] — Generates a lint for unused values. | |
227 | - ABI, linking, symbols, and FFI | |
228 | - [`link`] — Specifies a native library to link with an `extern` block. | |
229 | - [`link_name`] — Specifies the name of the symbol for functions or statics | |
230 | in an `extern` block. | |
231 | - [`no_link`] — Prevents linking an extern crate. | |
232 | - [`repr`] — Controls type layout. | |
233 | - [`crate_type`] — Specifies the type of crate (library, executable, etc.). | |
234 | - [`no_main`] — Disables emitting the `main` symbol. | |
235 | - [`export_name`] — Specifies the exported symbol name for a function or | |
236 | static. | |
237 | - [`link_section`] — Specifies the section of an object file to use for a | |
238 | function or static. | |
239 | - [`no_mangle`] — Disables symbol name encoding. | |
240 | - [`used`] — Forces the compiler to keep a static item in the output | |
241 | object file. | |
242 | - [`crate_name`] — Specifies the crate name. | |
243 | - Code generation | |
244 | - [`inline`] — Hint to inline code. | |
245 | - [`cold`] — Hint that a function is unlikely to be called. | |
246 | - [`no_builtins`] — Disables use of certain built-in functions. | |
247 | - [`target_feature`] — Configure platform-specific code generation. | |
3dfed10e | 248 | - [`track_caller`] - Pass the parent call location to `std::panic::Location::caller()`. |
532ac7d7 XL |
249 | - Documentation |
250 | - `doc` — Specifies documentation. See [The Rustdoc Book] for more | |
251 | information. [Doc comments] are transformed into `doc` attributes. | |
252 | - Preludes | |
253 | - [`no_std`] — Removes std from the prelude. | |
254 | - [`no_implicit_prelude`] — Disables prelude lookups within a module. | |
255 | - Modules | |
256 | - [`path`] — Specifies the filename for a module. | |
257 | - Limits | |
258 | - [`recursion_limit`] — Sets the maximum recursion limit for certain | |
259 | compile-time operations. | |
260 | - [`type_length_limit`] — Sets the maximum size of a polymorphic type. | |
261 | - Runtime | |
262 | - [`panic_handler`] — Sets the function to handle panics. | |
263 | - [`global_allocator`] — Sets the global memory allocator. | |
264 | - [`windows_subsystem`] — Specifies the windows subsystem to link with. | |
265 | - Features | |
266 | - `feature` — Used to enable unstable or experimental compiler features. See | |
267 | [The Unstable Book] for features implemented in `rustc`. | |
e74abb32 XL |
268 | - Type System |
269 | - [`non_exhaustive`] — Indicate that a type will have more fields/variants | |
270 | added in future. | |
cc61c64b | 271 | |
416331ca | 272 | [Doc comments]: comments.md#doc-comments |
532ac7d7 XL |
273 | [ECMA-334]: https://www.ecma-international.org/publications/standards/Ecma-334.htm |
274 | [ECMA-335]: https://www.ecma-international.org/publications/standards/Ecma-335.htm | |
416331ca XL |
275 | [Expression Attributes]: expressions.md#expression-attributes |
276 | [IDENTIFIER]: identifiers.md | |
277 | [RAW_STRING_LITERAL]: tokens.md#raw-string-literals | |
278 | [STRING_LITERAL]: tokens.md#string-literals | |
532ac7d7 XL |
279 | [The Rustdoc Book]: ../rustdoc/the-doc-attribute.html |
280 | [The Unstable Book]: ../unstable-book/index.html | |
416331ca | 281 | [_DelimTokenTree_]: macros.md |
17df50a5 | 282 | [_Expression_]: expressions.md |
416331ca XL |
283 | [_SimplePath_]: paths.md#simple-paths |
284 | [`allow`]: attributes/diagnostics.md#lint-check-attributes | |
ba9703b0 | 285 | [`automatically_derived`]: attributes/derive.md#the-automatically_derived-attribute |
416331ca XL |
286 | [`cfg_attr`]: conditional-compilation.md#the-cfg_attr-attribute |
287 | [`cfg`]: conditional-compilation.md#the-cfg-attribute | |
288 | [`cold`]: attributes/codegen.md#the-cold-attribute | |
289 | [`crate_name`]: crates-and-source-files.md#the-crate_name-attribute | |
290 | [`crate_type`]: linkage.md | |
291 | [`deny`]: attributes/diagnostics.md#lint-check-attributes | |
292 | [`deprecated`]: attributes/diagnostics.md#the-deprecated-attribute | |
293 | [`derive`]: attributes/derive.md | |
294 | [`export_name`]: abi.md#the-export_name-attribute | |
295 | [`forbid`]: attributes/diagnostics.md#lint-check-attributes | |
296 | [`global_allocator`]: runtime.md#the-global_allocator-attribute | |
297 | [`ignore`]: attributes/testing.md#the-ignore-attribute | |
298 | [`inline`]: attributes/codegen.md#the-inline-attribute | |
299 | [`link_name`]: items/external-blocks.md#the-link_name-attribute | |
300 | [`link_section`]: abi.md#the-link_section-attribute | |
301 | [`link`]: items/external-blocks.md#the-link-attribute | |
302 | [`macro_export`]: macros-by-example.md#path-based-scope | |
303 | [`macro_use`]: macros-by-example.md#the-macro_use-attribute | |
416331ca XL |
304 | [`must_use`]: attributes/diagnostics.md#the-must_use-attribute |
305 | [`no_builtins`]: attributes/codegen.md#the-no_builtins-attribute | |
5869c6ff | 306 | [`no_implicit_prelude`]: names/preludes.md#the-no_implicit_prelude-attribute |
416331ca XL |
307 | [`no_link`]: items/extern-crates.md#the-no_link-attribute |
308 | [`no_main`]: crates-and-source-files.md#the-no_main-attribute | |
309 | [`no_mangle`]: abi.md#the-no_mangle-attribute | |
5869c6ff | 310 | [`no_std`]: names/preludes.md#the-no_std-attribute |
e74abb32 | 311 | [`non_exhaustive`]: attributes/type_system.md#the-non_exhaustive-attribute |
416331ca XL |
312 | [`panic_handler`]: runtime.md#the-panic_handler-attribute |
313 | [`path`]: items/modules.md#the-path-attribute | |
314 | [`proc_macro_attribute`]: procedural-macros.md#attribute-macros | |
315 | [`proc_macro_derive`]: procedural-macros.md#derive-macros | |
316 | [`proc_macro`]: procedural-macros.md#function-like-procedural-macros | |
317 | [`recursion_limit`]: attributes/limits.md#the-recursion_limit-attribute | |
318 | [`repr`]: type-layout.md#representations | |
319 | [`should_panic`]: attributes/testing.md#the-should_panic-attribute | |
320 | [`target_feature`]: attributes/codegen.md#the-target_feature-attribute | |
321 | [`test`]: attributes/testing.md#the-test-attribute | |
3dfed10e | 322 | [`track_caller`]: attributes/codegen.md#the-track_caller-attribute |
416331ca XL |
323 | [`type_length_limit`]: attributes/limits.md#the-type_length_limit-attribute |
324 | [`used`]: abi.md#the-used-attribute | |
325 | [`warn`]: attributes/diagnostics.md#lint-check-attributes | |
326 | [`windows_subsystem`]: runtime.md#the-windows_subsystem-attribute | |
327 | [attribute macros]: procedural-macros.md#attribute-macros | |
328 | [block expressions]: expressions/block-expr.md | |
532ac7d7 | 329 | [built-in attributes]: #built-in-attributes-index |
416331ca XL |
330 | [derive macro helper attributes]: procedural-macros.md#derive-macro-helper-attributes |
331 | [enum]: items/enumerations.md | |
332 | [expression statement]: statements.md#expression-statements | |
333 | [external blocks]: items/external-blocks.md | |
334 | [functions]: items/functions.md | |
335 | [generics]: items/generics.md | |
336 | [implementations]: items/implementations.md | |
337 | [item declarations]: items.md | |
338 | [match expressions]: expressions/match-expr.md | |
339 | [modules]: items/modules.md | |
340 | [statements]: statements.md | |
341 | [struct]: items/structs.md | |
5869c6ff | 342 | [tool prelude]: names/preludes.md#tool-prelude |
416331ca | 343 | [union]: items/unions.md |
e74abb32 XL |
344 | [closure]: expressions/closure-expr.md |
345 | [function pointer]: types/function-pointer.md | |
346 | [variadic functions]: items/external-blocks.html#variadic-functions |