Attributes

Anattribute is a general, free-form metadatum that is interpreted accordingto name, convention, language, and compiler version. Attributes are modeledon Attributes inECMA-335, with the syntax coming fromECMA-334 (C#).

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

The attribute consists of a path to the attribute, followed by an optionaldelimited token tree whose interpretation is defined by the attribute.Attributes other than macro attributes also allow the input to be an equalssign (=) followed by an expression. See themeta itemsyntax below for more details.

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

The following attributes are unsafe:

• export_name
• link_section
• naked
• no_mangle

Attributes can be classified into the following kinds:

• Built-in attributes
• Proc macro attributes
• Derive macro helper attributes
• Tool attributes

Attributes may be applied to many things in the language:

• Allitem declarations accept outer attributes whileexternal blocks,functions,implementations, andmodules accept inner attributes.
• Moststatements accept outer attributes (seeExpression Attributes forlimitations on expression statements).
• Block expressions accept outer and inner attributes, but only when they arethe outer expression of anexpression statement or the final expression ofanother block expression.
• Enum variants andstruct andunion fields accept outer attributes.
• Match expression arms accept outer attributes.
• Generic lifetime or type parameter accept outer attributes.
• Expressions accept outer attributes in limited situations, seeExpressionAttributes for details.
• Function,closure andfunction pointerparameters accept outer attributes. This includes attributes on variadic parametersdenoted with... in function pointers andexternal blocks.

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 = ();}}

Meta Item Attribute Syntax

A “meta item” is the syntax used for theAttr rule by mostbuilt-inattributes. It has the following grammar:

Expressions in meta items must macro-expand to literal expressions, which must notinclude integer or float type suffixes. Expressions which are not literal expressionswill 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 expandedafter that outer macro. For example, the following code will expand theSerialize proc-macro first, which must preserve theinclude_str! call inorder 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 thirdfn foo() {}

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

Some examples of meta items are:

Active and inert attributes

An attribute is either active or inert. During attribute processing,activeattributes remove themselves from the thing they are on whileinert attributesstay on.

Thecfg andcfg_attr attributes are active.Attribute macros are active. All other attributes are inert.

Tool attributes

The compiler may allow attributes for external tools where each tool residesin its own module in thetool prelude. The first segment of the attributepath is the name of the tool, with one or more additional segments whoseinterpretation is up to the tool.

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

Tool attributes are not available if theno_implicit_prelude attribute isused.

#![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() {}}

Built-in attributes index

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

• Conditional compilation

  • cfg — Controls conditional compilation.
  • cfg_attr — Conditionally includes attributes.

• Testing

  • test — Marks a function as a test.
  • ignore — Disables a test function.
  • should_panic — Indicates a test should generate a panic.

• Derive

  • derive — Automatic trait implementations.
  • automatically_derived — Marker for implementations created byderive.

• Macros

  • macro_export — Exports amacro_rules macro for cross-crate usage.
  • macro_use — Expands macro visibility, or imports macros from othercrates.
  • proc_macro — Defines a function-like macro.
  • proc_macro_derive — Defines a derive macro.
  • proc_macro_attribute — Defines an attribute macro.

• Diagnostics

  • allow,expect,warn,deny,forbid — Alters the default lint level.
  • deprecated — Generates deprecation notices.
  • must_use — Generates a lint for unused values.
  • diagnostic::on_unimplemented — Hints the compiler to emit a certain errormessage if a trait is not implemented.
  • diagnostic::do_not_recommend — Hints the compiler to not show a certain trait impl in error messages.

• ABI, linking, symbols, and FFI

  • link — Specifies a native library to link with anextern block.
  • link_name — Specifies the name of the symbol for functions or staticsin anextern block.
  • link_ordinal — Specifies the ordinal of the symbol for functions orstatics in anextern block.
  • no_link — Prevents linking an extern crate.
  • repr — Controls type layout.
  • crate_type — Specifies the type of crate (library, executable, etc.).
  • no_main — Disables emitting themain symbol.
  • export_name — Specifies the exported symbol name for a function orstatic.
  • link_section — Specifies the section of an object file to use for afunction or static.
  • no_mangle — Disables symbol name encoding.
  • used — Forces the compiler to keep a static item in the outputobject file.
  • crate_name — Specifies the crate name.

• Code generation

  • inline — Hint to inline code.
  • cold — Hint that a function is unlikely to be called.
  • naked - Prevent the compiler from emitting a function prologue.
  • no_builtins — Disables use of certain built-in functions.
  • target_feature — Configure platform-specific code generation.
  • track_caller — Pass the parent call location tostd::panic::Location::caller().
  • instruction_set — Specify the instruction set used to generate a functions code

• Documentation

  • doc — Specifies documentation. SeeThe Rustdoc Book for moreinformation.Doc comments are transformed intodoc attributes.

• Preludes

  • no_std — Removes std from the prelude.
  • no_implicit_prelude — Disables prelude lookups within a module.

• Modules

  • path — Specifies the filename for a module.

• Limits

  • recursion_limit — Sets the maximum recursion limit for certaincompile-time operations.
  • type_length_limit — Sets the maximum size of a polymorphic type.

• Runtime

  • panic_handler — Sets the function to handle panics.
  • global_allocator — Sets the global memory allocator.
  • windows_subsystem — Specifies the windows subsystem to link with.

• Features

  • feature — Used to enable unstable or experimental compiler features. SeeThe Unstable Book for features implemented inrustc.

• Type System

  • non_exhaustive — Indicate that a type will have more fields/variantsadded in future.

• Debugger

  • debugger_visualizer — Embeds a file that specifies debugger output for a type.
  • collapse_debuginfo — Controls how macro invocations are encoded in debuginfo.