]> git.proxmox.com Git - rustc.git/blame - src/doc/reference/src/attributes.md
New upstream version 1.44.1+dfsg1
[rustc.git] / src / doc / reference / src / attributes.md
CommitLineData
532ac7d7 1{{#include attributes-redirect.html}}
8bb4bdeb
XL
2# Attributes
3
8faf50e0 4> **<sup>Syntax</sup>**\
8faf50e0 5> _InnerAttribute_ :\
532ac7d7 6> &nbsp;&nbsp; `#` `!` `[` _Attr_ `]`
8faf50e0
XL
7>
8> _OuterAttribute_ :\
532ac7d7 9> &nbsp;&nbsp; `#` `[` _Attr_ `]`
8faf50e0 10>
532ac7d7
XL
11> _Attr_ :\
12> &nbsp;&nbsp; [_SimplePath_] _AttrInput_<sup>?</sup>
8faf50e0 13>
532ac7d7
XL
14> _AttrInput_ :\
15> &nbsp;&nbsp; &nbsp;&nbsp; [_DelimTokenTree_]\
16> &nbsp;&nbsp; | `=` [_LiteralExpression_]<sub>_without suffix_</sub>
3b2f2976 17
8faf50e0 18An _attribute_ is a general, free-form metadatum that is interpreted according
e1599b0c 19to name, convention, language, and compiler version. Attributes are modeled
8faf50e0
XL
20on 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
23item that the attribute is declared within. _Outer attributes_, written without
24the bang after the hash, apply to the thing that follows the attribute.
8bb4bdeb 25
532ac7d7
XL
26The attribute consists of a path to the attribute, followed by an optional
27delimited token tree whose interpretation is defined by the attribute.
28Attributes other than macro attributes also allow the input to be an equals
29sign (`=`) followed by a literal expression. See the [meta item
30syntax](#meta-item-attribute-syntax) below for more details.
8bb4bdeb 31
532ac7d7 32Attributes 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
39Attributes 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
57Some 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]
65fn test_foo() {
66 /* ... */
67}
68
69// A conditionally-compiled module
041b39d2 70#[cfg(target_os = "linux")]
8bb4bdeb
XL
71mod bar {
72 /* ... */
73}
74
75// A lint attribute used to suppress a warning/error
76#[allow(non_camel_case_types)]
77type int8_t = i8;
8faf50e0 78
532ac7d7 79// Inner attribute applies to the entire function.
8faf50e0
XL
80fn 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 91A "meta item" is the syntax used for the _Attr_ rule by most [built-in
e74abb32 92attributes]. It has the following grammar:
8bb4bdeb 93
532ac7d7
XL
94> **<sup>Syntax</sup>**\
95> _MetaItem_ :\
96> &nbsp;&nbsp; &nbsp;&nbsp; [_SimplePath_]\
97> &nbsp;&nbsp; | [_SimplePath_] `=` [_LiteralExpression_]<sub>_without suffix_</sub>\
98> &nbsp;&nbsp; | [_SimplePath_] `(` _MetaSeq_<sup>?</sup> `)`
99>
100> _MetaSeq_ :\
101> &nbsp;&nbsp; _MetaItemInner_ ( `,` MetaItemInner )<sup>\*</sup> `,`<sup>?</sup>
102>
103> _MetaItemInner_ :\
104> &nbsp;&nbsp; &nbsp;&nbsp; _MetaItem_\
105> &nbsp;&nbsp; | [_LiteralExpression_]<sub>_without suffix_</sub>
83c7162d 106
532ac7d7
XL
107Literal expressions in meta items must not include integer or float type
108suffixes.
83c7162d 109
532ac7d7
XL
110Various built-in attributes use different subsets of the meta item syntax to
111specify their inputs. The following grammar rules show some commonly used
112forms:
83c7162d 113
532ac7d7
XL
114> **<sup>Syntax</sup>**\
115> _MetaWord_:\
116> &nbsp;&nbsp; [IDENTIFIER]
83c7162d 117>
532ac7d7
XL
118> _MetaNameValueStr_:\
119> &nbsp;&nbsp; [IDENTIFIER] `=` ([STRING_LITERAL] | [RAW_STRING_LITERAL])
83c7162d 120>
532ac7d7
XL
121> _MetaListPaths_:\
122> &nbsp;&nbsp; [IDENTIFIER] `(` ( [_SimplePath_] (`,` [_SimplePath_])* `,`<sup>?</sup> )<sup>?</sup> `)`
83c7162d 123>
532ac7d7
XL
124> _MetaListIdents_:\
125> &nbsp;&nbsp; [IDENTIFIER] `(` ( [IDENTIFIER] (`,` [IDENTIFIER])* `,`<sup>?</sup> )<sup>?</sup> `)`
83c7162d 126>
532ac7d7
XL
127> _MetaListNameValueStr_:\
128> &nbsp;&nbsp; [IDENTIFIER] `(` ( _MetaNameValueStr_ (`,` _MetaNameValueStr_)* `,`<sup>?</sup> )<sup>?</sup> `)`
9fa01778 129
532ac7d7 130Some examples of meta items are:
8bb4bdeb 131
532ac7d7
XL
132Style | 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
142An attribute is either active or inert. During attribute processing, *active
143attributes* remove themselves from the thing they are on while *inert attributes*
144stay on.
8bb4bdeb 145
532ac7d7
XL
146The [`cfg`] and [`cfg_attr`] attributes are active. The [`test`] attribute is
147inert when compiling for tests and active otherwise. [Attribute macros] are
148active. All other attributes are inert.
8bb4bdeb 149
532ac7d7 150## Tool attributes
b7449926 151
532ac7d7
XL
152The compiler may allow attributes for external tools where each tool resides
153in its own namespace. The first segment of the attribute path is the name of
154the tool, with one or more additional segments whose interpretation is up to
155the tool.
b7449926 156
532ac7d7
XL
157When a tool is not in use, the tool's attributes are accepted without a
158warning. When the tool is in use, the tool is responsible for processing and
159interpretation of its attributes.
8bb4bdeb 160
532ac7d7
XL
161Tool attributes are not available if the [`no_implicit_prelude`] attribute is
162used.
8bb4bdeb 163
cc61c64b 164```rust
532ac7d7
XL
165// Tells the rustfmt tool to not format the following element.
166#[rustfmt::skip]
167struct S {
8bb4bdeb 168}
8bb4bdeb 169
532ac7d7
XL
170// Controls the "cyclomatic complexity" threshold for the clippy tool.
171#[clippy::cyclomatic_complexity = "100"]
172pub 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
179The 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.
ba9703b0
XL
190 - [`automatically_derived`] — Marker for implementations created by
191 `derive`.
532ac7d7
XL
192- Macros
193 - [`macro_export`] — Exports a `macro_rules` macro for cross-crate usage.
194 - [`macro_use`] — Expands macro visibility, or imports macros from other
195 crates.
196 - [`proc_macro`] — Defines a function-like macro.
197 - [`proc_macro_derive`] — Defines a derive macro.
198 - [`proc_macro_attribute`] — Defines an attribute macro.
199- Diagnostics
200 - [`allow`], [`warn`], [`deny`], [`forbid`] — Alters the default lint level.
201 - [`deprecated`] — Generates deprecation notices.
202 - [`must_use`] — Generates a lint for unused values.
203- ABI, linking, symbols, and FFI
204 - [`link`] — Specifies a native library to link with an `extern` block.
205 - [`link_name`] — Specifies the name of the symbol for functions or statics
206 in an `extern` block.
207 - [`no_link`] — Prevents linking an extern crate.
208 - [`repr`] — Controls type layout.
209 - [`crate_type`] — Specifies the type of crate (library, executable, etc.).
210 - [`no_main`] — Disables emitting the `main` symbol.
211 - [`export_name`] — Specifies the exported symbol name for a function or
212 static.
213 - [`link_section`] — Specifies the section of an object file to use for a
214 function or static.
215 - [`no_mangle`] — Disables symbol name encoding.
216 - [`used`] — Forces the compiler to keep a static item in the output
217 object file.
218 - [`crate_name`] — Specifies the crate name.
219- Code generation
220 - [`inline`] — Hint to inline code.
221 - [`cold`] — Hint that a function is unlikely to be called.
222 - [`no_builtins`] — Disables use of certain built-in functions.
223 - [`target_feature`] — Configure platform-specific code generation.
224- Documentation
225 - `doc` — Specifies documentation. See [The Rustdoc Book] for more
226 information. [Doc comments] are transformed into `doc` attributes.
227- Preludes
228 - [`no_std`] — Removes std from the prelude.
229 - [`no_implicit_prelude`] — Disables prelude lookups within a module.
230- Modules
231 - [`path`] — Specifies the filename for a module.
232- Limits
233 - [`recursion_limit`] — Sets the maximum recursion limit for certain
234 compile-time operations.
235 - [`type_length_limit`] — Sets the maximum size of a polymorphic type.
236- Runtime
237 - [`panic_handler`] — Sets the function to handle panics.
238 - [`global_allocator`] — Sets the global memory allocator.
239 - [`windows_subsystem`] — Specifies the windows subsystem to link with.
240- Features
241 - `feature` — Used to enable unstable or experimental compiler features. See
242 [The Unstable Book] for features implemented in `rustc`.
e74abb32
XL
243- Type System
244 - [`non_exhaustive`] — Indicate that a type will have more fields/variants
245 added in future.
cc61c64b 246
416331ca 247[Doc comments]: comments.md#doc-comments
532ac7d7
XL
248[ECMA-334]: https://www.ecma-international.org/publications/standards/Ecma-334.htm
249[ECMA-335]: https://www.ecma-international.org/publications/standards/Ecma-335.htm
416331ca
XL
250[Expression Attributes]: expressions.md#expression-attributes
251[IDENTIFIER]: identifiers.md
252[RAW_STRING_LITERAL]: tokens.md#raw-string-literals
253[STRING_LITERAL]: tokens.md#string-literals
532ac7d7
XL
254[The Rustdoc Book]: ../rustdoc/the-doc-attribute.html
255[The Unstable Book]: ../unstable-book/index.html
416331ca
XL
256[_DelimTokenTree_]: macros.md
257[_LiteralExpression_]: expressions/literal-expr.md
258[_SimplePath_]: paths.md#simple-paths
259[`allow`]: attributes/diagnostics.md#lint-check-attributes
ba9703b0 260[`automatically_derived`]: attributes/derive.md#the-automatically_derived-attribute
416331ca
XL
261[`cfg_attr`]: conditional-compilation.md#the-cfg_attr-attribute
262[`cfg`]: conditional-compilation.md#the-cfg-attribute
263[`cold`]: attributes/codegen.md#the-cold-attribute
264[`crate_name`]: crates-and-source-files.md#the-crate_name-attribute
265[`crate_type`]: linkage.md
266[`deny`]: attributes/diagnostics.md#lint-check-attributes
267[`deprecated`]: attributes/diagnostics.md#the-deprecated-attribute
268[`derive`]: attributes/derive.md
269[`export_name`]: abi.md#the-export_name-attribute
270[`forbid`]: attributes/diagnostics.md#lint-check-attributes
271[`global_allocator`]: runtime.md#the-global_allocator-attribute
272[`ignore`]: attributes/testing.md#the-ignore-attribute
273[`inline`]: attributes/codegen.md#the-inline-attribute
274[`link_name`]: items/external-blocks.md#the-link_name-attribute
275[`link_section`]: abi.md#the-link_section-attribute
276[`link`]: items/external-blocks.md#the-link-attribute
277[`macro_export`]: macros-by-example.md#path-based-scope
278[`macro_use`]: macros-by-example.md#the-macro_use-attribute
416331ca
XL
279[`must_use`]: attributes/diagnostics.md#the-must_use-attribute
280[`no_builtins`]: attributes/codegen.md#the-no_builtins-attribute
281[`no_implicit_prelude`]: items/modules.md#prelude-items
282[`no_link`]: items/extern-crates.md#the-no_link-attribute
283[`no_main`]: crates-and-source-files.md#the-no_main-attribute
284[`no_mangle`]: abi.md#the-no_mangle-attribute
285[`no_std`]: crates-and-source-files.md#preludes-and-no_std
e74abb32 286[`non_exhaustive`]: attributes/type_system.md#the-non_exhaustive-attribute
416331ca
XL
287[`panic_handler`]: runtime.md#the-panic_handler-attribute
288[`path`]: items/modules.md#the-path-attribute
289[`proc_macro_attribute`]: procedural-macros.md#attribute-macros
290[`proc_macro_derive`]: procedural-macros.md#derive-macros
291[`proc_macro`]: procedural-macros.md#function-like-procedural-macros
292[`recursion_limit`]: attributes/limits.md#the-recursion_limit-attribute
293[`repr`]: type-layout.md#representations
294[`should_panic`]: attributes/testing.md#the-should_panic-attribute
295[`target_feature`]: attributes/codegen.md#the-target_feature-attribute
296[`test`]: attributes/testing.md#the-test-attribute
297[`type_length_limit`]: attributes/limits.md#the-type_length_limit-attribute
298[`used`]: abi.md#the-used-attribute
299[`warn`]: attributes/diagnostics.md#lint-check-attributes
300[`windows_subsystem`]: runtime.md#the-windows_subsystem-attribute
301[attribute macros]: procedural-macros.md#attribute-macros
302[block expressions]: expressions/block-expr.md
532ac7d7 303[built-in attributes]: #built-in-attributes-index
416331ca
XL
304[derive macro helper attributes]: procedural-macros.md#derive-macro-helper-attributes
305[enum]: items/enumerations.md
306[expression statement]: statements.md#expression-statements
307[external blocks]: items/external-blocks.md
308[functions]: items/functions.md
309[generics]: items/generics.md
310[implementations]: items/implementations.md
311[item declarations]: items.md
312[match expressions]: expressions/match-expr.md
313[modules]: items/modules.md
314[statements]: statements.md
315[struct]: items/structs.md
316[union]: items/unions.md
e74abb32
XL
317[closure]: expressions/closure-expr.md
318[function pointer]: types/function-pointer.md
319[variadic functions]: items/external-blocks.html#variadic-functions