Attributes - The Rust Reference (original) (raw)

The Rust Reference

Attributes

Syntax
InnerAttribute :
# ! [ Attr ]

OuterAttribute :
# [ Attr ]

Attr :
SimplePath AttrInput?
| unsafe ( SimplePath AttrInput? )

AttrInput :
DelimTokenTree
| = Expression

An attribute is a general, free-form metadatum that is interpreted according to name, convention, language, and compiler version. Attributes are modeled on Attributes in ECMA-335, with the syntax coming from ECMA-334 (C#).

Inner attributes, written with a bang (!) after the hash (#), apply to the item that the attribute is declared within. Outer attributes, written without the bang after the hash, apply to the thing that follows the attribute.

The attribute consists of a path to the attribute, followed by an optional delimited token tree whose interpretation is defined by the attribute. Attributes other than macro attributes also allow the input to be an equals sign (=) followed by an expression. See the meta item syntax below for more details.

An attribute may be unsafe to apply. To avoid undefined behavior when using these attributes, certain obligations that cannot be checked by the compiler must be met. To assert these have been, the attribute is wrapped inunsafe(..), e.g. #[unsafe(no_mangle)].

The following attributes are unsafe:

Attributes can be classified into the following kinds:

Attributes may be applied to many things in the language:

Some examples of attributes:

#![allow(unused)]
fn main() {
// General metadata applied to the enclosing module or crate.
#![crate_type = "lib"]

// A function marked as a unit test
#[test]
fn test_foo() {
    /* ... */
}

// A conditionally-compiled module
#[cfg(target_os = "linux")]
mod bar {
    /* ... */
}

// A lint attribute used to suppress a warning/error
#[allow(non_camel_case_types)]
type int8_t = i8;

// Inner attribute applies to the entire function.
fn some_unused_variables() {
  #![allow(unused_variables)]

  let x = ();
  let y = ();
  let z = ();
}
}

A “meta item” is the syntax used for the Attr rule by most built-in attributes. It has the following grammar:

Syntax
MetaItem :
SimplePath
| SimplePath = Expression
| SimplePath ( MetaSeq? )

MetaSeq :
MetaItemInner ( , MetaItemInner )* ,?

MetaItemInner :
MetaItem
| Expression

Expressions in meta items must macro-expand to literal expressions, which must not include integer or float type suffixes. Expressions which are not literal expressions will be syntactically accepted (and can be passed to proc-macros), but will be rejected after parsing.

Note that if the attribute appears within another macro, it will be expanded after that outer macro. For example, the following code will expand theSerialize proc-macro first, which must preserve the include_str! call in order for it to be expanded:

#[derive(Serialize)]
struct Foo {
    #[doc = include_str!("x.md")]
    x: u32
}

Additionally, macros in attributes will be expanded only after all other attributes applied to the item:

#[macro_attr1] // expanded first
#[doc = mac!()] // `mac!` is expanded fourth.
#[macro_attr2] // expanded second
#[derive(MacroDerive1, MacroDerive2)] // expanded third
fn foo() {}

Various built-in attributes use different subsets of the meta item syntax to specify their inputs. The following grammar rules show some commonly used forms:

Syntax
MetaWord:
IDENTIFIER

MetaNameValueStr:
IDENTIFIER = (STRING_LITERAL | RAW_STRING_LITERAL)

MetaListPaths:
IDENTIFIER ( ( SimplePath (, SimplePath)* ,? )? )

MetaListIdents:
IDENTIFIER ( ( IDENTIFIER (, IDENTIFIER)* ,? )? )

MetaListNameValueStr:
IDENTIFIER ( ( MetaNameValueStr (, MetaNameValueStr)* ,? )? )

Some examples of meta items are:

Style Example
MetaWord no_std
MetaNameValueStr doc = "example"
MetaListPaths allow(unused, clippy::inline_always)
MetaListIdents macro_use(foo, bar)
MetaListNameValueStr link(name = "CoreFoundation", kind = "framework")

Active and inert attributes

An attribute is either active or inert. During attribute processing, active attributes remove themselves from the thing they are on while _inert attributes_stay on.

The cfg and cfg_attr attributes are active.Attribute macros are active. All other attributes are inert.

The compiler may allow attributes for external tools where each tool resides in its own module in the tool prelude. The first segment of the attribute path is the name of the tool, with one or more additional segments whose interpretation is up to the tool.

When a tool is not in use, the tool’s attributes are accepted without a warning. When the tool is in use, the tool is responsible for processing and interpretation of its attributes.

Tool attributes are not available if the no_implicit_prelude attribute is used.

#![allow(unused)]
fn main() {
// Tells the rustfmt tool to not format the following element.
#[rustfmt::skip]
struct S {
}

// Controls the "cyclomatic complexity" threshold for the clippy tool.
#[clippy::cyclomatic_complexity = "100"]
pub fn f() {}
}

Note: rustc currently recognizes the tools “clippy”, “rustfmt”, “diagnostic”, “miri” and “rust_analyzer”.

Built-in attributes index

The following is an index of all built-in attributes.