13. Attributes¶

Syntax

InnerAttributeOrDoc ::=
    InnerAttribute
  | InnerBuiltinAttribute
  | InnerBlockDoc
  | InnerLineDoc

InnerAttribute ::=
    #![ AttributeContent ]

OuterAttributeOrDoc ::=
    OuterAttribute
  | OuterBuiltinAttribute
  | OuterBlockDoc
  | OuterLineDoc

OuterAttribute ::=
    #[ AttributeContent ]

AttributeContent ::=
    SimplePath AttributeInput?

AttributeInput ::=
    ( TokenTree* )
  | = Expression

AttributeContentList ::=
    AttributeContent (, AttributeContent)* ,?

Legality Rules

13:1 An attribute is a general, free-form metadatum that is interpreted based on its name, convention, language, and tool.

13:2 An inner attribute is an attribute that applies to an enclosing item.

13:3 An outer attribute is an attribute that applies to a subsequent item.

13:4 An attribute content is a construct that provides the content of an attribute.

Examples

#[cfg[target_os = "linux"]]
mod linux_only_module {
    #![allow(unused_variables)]

    let unused = ();
}

13.1. Attribute Properties¶

Legality Rules

13.1:1 An active attribute is an attribute that is removed from the item it decorates.

13.1:2 An inert attribute is an attribute that remains with the item it decorates.

13.1:3 The following attributes are active attributes:

13.1:7 Attribute test is an inert attribute when compiling for testing purposes, otherwise it is an active attribute.

13.1:8 All remaining attributes are inert attributes.

13.2. Built-in Attributes¶

Syntax

InnerBuiltinAttribute ::=
    #![ BuiltinAttributeContent ]

OuterBuiltinAttribute ::=
    #[ BuiltinAttributeContent ]

BuiltinAttributeContent ::=
    AutomaticallyDerivedContent
  | CfgAttrContent
  | CfgContent
  | CollapseDebuginfoContent
  | ColdContent
  | CrateNameContent
  | CrateTypeContent
  | DeriveContent
  | DocContent
  | ExportNameContent
  | GlobalAllocatorContent
  | InlineContent
  | IgnoreContent
  | LinkContent
  | LinkNameContent
  | LinkSectionContent
  | LinkOrdinalContent
  | MacroExportContent
  | MacroUseContent
  | NakedContent
  | NoBinutilsContent
  | NoImplicitPreludeContent
  | NoLinkContent
  | NoMainContent
  | NoMangleContent
  | NonExhaustiveContent
  | NoStdContent
  | PanicHandlerContent
  | PathContent
  | ProcMacroAttributeContent
  | ProcMacroContent
  | ProcMacroDeriveContent
  | RecursionLimitContent
  | ReprContent
  | ShouldPanicContent
  | TargetFeatureContent
  | TestContent
  | TrackCallerContent
  | TypeLengthLimitContent
  | UnsafeContent
  | UsedContent
  | WindowsSubsystemContent

Legality Rules

13.2:1 A built-in attribute is a language-defined attribute.

13.2:2 The following built-in attributes are code generation attributes:

13.2:9 The following built-in attributes are conditional compilation attributes:

13.2:10 Attribute cfg.
13.2:11 Attribute cfg_attr.

13.2:12 The following built-in attributes are derivation attributes:

13.2:13 Attribute automatically_derived.
13.2:14 Attribute derive.

13.2:15 The following built-in attributes are diagnostics attributes:

13.2:16 Attribute allow.
13.2:17 Attribute deny.
13.2:18 Attribute deprecated.
13.2:19 Attribute forbid.
13.2:20 Attribute must_use.
13.2:21 Attribute warn.
13.2:22 Attribute expect.
13.2:23 Attribute unsafe.

13.2:24 The following built-in attributes are documentation attributes:

13.2:25 Attribute doc.

13.2:26 The following built-in attributes are foreign function interface attributes:

13.2:38 The following built-in attributes are limits attributes:

13.2:39 Attribute recursion_limit.
13.2:40 Attribute type_length_limit.

13.2:41 The following built-in attributes are macro attributes:

13.2:42 Attribute macro_export.
13.2:43 Attribute macro_use.
13.2:44 Attribute proc_macro.
13.2:45 Attribute proc_macro_attribute.
13.2:46 Attribute proc_macro_derive.

13.2:47 The following built-in attributes are modules attributes:

13.2:48 Attribute path.

13.2:49 The following built-in attributes are prelude attributes:

13.2:50 Attribute no_implicit_prelude.
13.2:51 Attribute no_std.

13.2:52 The following built-in attributes are runtime attributes:

13.2:53 Attribute global_allocator.
13.2:54 Attribute panic_handler.
13.2:55 Attribute windows_subsystem.

13.2:56 The following built-in attributes are testing attributes:

13.2:60 The following built-in attributes are type attributes:

13.2:61 Attribute non_exhaustive.

13.2.1. Code Generation Attributes¶

13.2.1.1. Attribute `cold`¶

Syntax

ColdContent ::=
    cold

Legality Rules

13.2.1.1:1 Attribute cold shall apply to functions.

13.2.1.1:2 Attribute cold indicates that its related function is unlikely to be called.

Examples

#[cold]
fn rarely_called_function () {}

13.2.1.2. Attribute `inline`¶

Syntax

InlineContent ::=
    inline InlineHint?

InlineHint ::=
    ( (always | never) )

Legality Rules

13.2.1.2:1 Attribute inline shall apply to closure expressions and functions.

13.2.1.2:2 Attribute inline marks its related function as inlined. The process of replacing a call expression to an inlined function with the function body is referred to as inlining.

13.2.1.2:3 Attribute inline without an InlineHint suggests to a tool that inlining should be performed.

13.2.1.2:4 Attribute inline with InlineHint always suggests to a tool that inlining should always be performed.

13.2.1.2:5 Attribute inline with InlineHint never suggests to a tool that inlining should never be performed.

13.2.1.2:6 A tool is not obliged to perform inlining.

Examples

#[inline]
fn suggests_inlining() {}

#[inline(always)]
fn requests_consistent_inlining() {}

#[inline(never)]
fn requests_suppressed_inlining() {}

13.2.1.3. Attribute `no_builtins`¶

Syntax

NoBinutilsContent ::=
    no_builtins

Legality Rules

13.2.1.3:1 Attribute no_builtins shall apply to the crate root module.

13.2.1.3:2 Attribute no_builtins prevents the tool from replacing certain code patterns with calls to intrinsic functions.

Examples

#![no_builtins]

13.2.1.4. Attribute `target_feature`¶

Syntax

TargetFeatureContent ::=
    target_feature ( enable = " FeatureList " )

FeatureList ::=
    Feature (, Feature)*

Feature ::=
    adx
  | aes
  | avx
  | avx2
  | avx512bf16
  | avx512bitalg
  | avx512bw
  | avx512cd
  | avx512dq
  | avx512f
  | avx512fp16
  | avx512ifma
  | avx512vbmi
  | avx512vbmi2
  | avx512vl
  | avx512vnni
  | avx512vp2intersect
  | avx512vpopcntdq
  | avxifma
  | avxneconvert
  | avxvnni
  | avxvnniint16
  | avxvnniint8
  | bmi1
  | bmi2
  | fma
  | fxsr
  | gfni
  | kl
  | lzcnt
  | pclmulqdq
  | popcnt
  | rdrand
  | rdseed
  | sha
  | sha512
  | sm3
  | sm4
  | sse
  | sse2
  | sse3
  | sse4.1
  | sse4.2
  | ssse3
  | vaes
  | vpclmulqdq
  | widekl
  | xsave
  | xsavec
  | xsaveopt
  | xsaves

Legality Rules

13.2.1.4:1 Safe functions that are annotated with target_features can only be called without an unsafe block by a caller that is within a function that enables all the target_features that the callee enables.

13.2.1.4:2 Attribute target_feature enables target architecture features for its related function.

13.2.1.4:3 The target architecture features are as follows:

13.2.1.4:4	Feature	implicitly enables	Description
13.2.1.4:5	adx		Intel Multi-Precision Add-Cary Instruction Extensions
13.2.1.4:6	aes	sse2	Advanced Encryption Standard
13.2.1.4:7	avx	sse4.2	Advanced Vector Extensions
13.2.1.4:8	avx2	avx	Advanced Vector Extensions 2
13.2.1.4:9	avx512bf16	avx512bw	Advanced Vector Extensions 512-bit - Bfloat16 Extensions
13.2.1.4:10	vx512bitalg	avx512bw	Advanced Vector Extensions 512-bit - Bit Algorithms
13.2.1.4:11	avx512bw	avx512f	Advanced Vector Extensions 512-bit - Byte and Word Instructions
13.2.1.4:12	avx512cd	avx512f	Advanced Vector Extensions 512-bit - Conflict Detection Instructions
13.2.1.4:13	avx512dq	avx512f	Advanced Vector Extensions 512-bit - Doubleword and Quadword Instructions
13.2.1.4:14	avx512f	avx2, fma, f16c	Advanced Vector Extensions 512-bit - Foundation
13.2.1.4:15	avx512fp16	avx512bw	Advanced Vector Extensions 512-bit - Float16 Extensions
13.2.1.4:16	avx512ifma	avx512f	Advanced Vector Extensions 512-bit - Integer Fused Multiply Add
13.2.1.4:17	avx512vbmi	avx512bw	Advanced Vector Extensions 512-bit - Vector Byte Manipulation Instructions
13.2.1.4:18	avx512vbmi2	avx512bw	Advanced Vector Extensions 512-bit - Vector Byte Manipulation Instructions 2
13.2.1.4:19	avx512vl	avx512f	Advanced Vector Extensions 512-bit - Vector Length Extensions
13.2.1.4:20	avx512vnni	avx512f	Advanced Vector Extensions 512-bit - Vector Neural Network Instructions
13.2.1.4:21	avx512vp2intersect	avx512f	Advanced Vector Extensions 512-bit - Vector Pair Intersection to a Pair of Mask Registers
13.2.1.4:22	avx512vpopcntdq	avx512f	Advanced Vector Extensions 512-bit - Vector Population Count Instruction
13.2.1.4:23	avxifma	avx2	Advanced Vector Extensions - Integer Fused Multiply Add
13.2.1.4:24	avxneconvert	avx2	Advanced Vector Extensions - No-Exception Floating-Point conversion Instructions
13.2.1.4:25	avxvnni	avx2	Advanced Vector Extensions - Vector Neural Network Instructions
13.2.1.4:26	avxvnniint16	avx2	Advanced Vector Extensions - Vector Neural Network Instructions with 16-bit Integers
13.2.1.4:27	avxvnniint8	avx2	Advanced Vector Extensions - Vector Neural Network Instructions with 8-bit Integers
13.2.1.4:28	bmi1		Bit Manipulation Instruction Sets
13.2.1.4:29	bmi2		Bit Manipulation Instruction Sets 2
13.2.1.4:30	fma	avx	Three-operand fused multiply-add
13.2.1.4:31	fxsr		Save and restore x87 FPU, MMX technology, and SSE state
13.2.1.4:32	gfni	sse2	Galois Field New Instructions
13.2.1.4:33	kl	sse2	Intel Key Locker Instructions
13.2.1.4:34	lzcnt		Leading zeros count
13.2.1.4:35	pclmulqdq	sse2	Packed carry-less multiplication quadword
13.2.1.4:36	popcnt		Count of bits set to 1
13.2.1.4:37	rdrand		Read random number
13.2.1.4:38	rdseed		Read random seed
13.2.1.4:39	sha	sse2	Secure Hash Algorithm
13.2.1.4:40	sha512	avx2	Secure Hash Algorithm with 512-bit digest
13.2.1.4:41	sm3	avx	ShangMi 3 Hash Algorithm
13.2.1.4:42	sm4	avx2	ShangMi 4 Hash Algorithm
13.2.1.4:43	sse		Streaming SIMD Extensions
13.2.1.4:44	sse2	sse	Streaming SIMD Extensions 2
13.2.1.4:45	sse3	sse2	Streaming SIMD Extensions 3
13.2.1.4:46	sse4.1	sse3	Streaming SIMD Extensions 4.1
13.2.1.4:47	sse4.2.	sse4.1	Streaming SIMD Extensions 4.2
13.2.1.4:48	ssse3	sse3	Supplemental Streaming SIMD Extensions 3
13.2.1.4:49	vaes	avx2, aes	Vector AES Instructions
13.2.1.4:50	vpclmulqdq	avx, pclmulqdq	Vector Carry-less multiplication of Quadwords
13.2.1.4:51	widekl	kl	Intel Wide Keylocker Instructions
13.2.1.4:52	xsave		Save processor extended status
13.2.1.4:53	xsavec		Save processor extended status with compaction
13.2.1.4:54	xsaveopt		Save processor extended states optimized
13.2.1.4:55	xsaves		Save processor extended states supervizor

Undefined Behavior

13.2.1.4:56 It is undefined behavior to execute a program compiled with target architecture features that are not supported.

Examples

#[target_feature(enable="bmi1,sse4.1")]
fn requires_target_architecture_features () {}

13.2.1.5. Attribute `track_caller`¶

Syntax

TrackCallerContent ::=
    track_caller

Legality Rules

13.2.1.5:1 Attribute track_caller shall apply to non-main functions with ABI “Rust”.

13.2.1.5:2 Attribute track_caller allows the function body of its related function to obtain a core::panic::Location which indicates the topmost untracked caller that ultimately led to the invocation of the function.

13.2.1.5:3 A tool is not required to implement this indication in an effective manner.

13.2.1.5:4 When applied to an associated trait function, attribute track_caller applies to all associated functions of the implemented trait. If the associated trait function has a default implementation, then the attribute applies to all overriding functions.

Undefined Behavior

13.2.1.5:5 It is undefined behavior when attribute track_caller applies to an external function but does not apply to all linked implementations.

13.2.1.5:6 It is undefined behavior when attribute track_caller is applied to an exported function but the external function it links to is missing the attribute.

Examples

#[track_caller]
fn who_called_me () {}

13.2.1.6. Attribute `naked`¶

Syntax

NakedContent ::=
    naked

Legality Rules

13.2.1.6:1 Attribute naked shall apply to functions.

13.2.1.6:2 Attribute naked ensures that a function prologue and epilogue are not generated.

13.2.1.6:3 Attribute naked function body must consist of exactly one macro core::arch::naked_asm call.

13.2.1.6:4 Attribute naked cannot be used together with testing functions.

13.2.1.6:5 Attribute naked cannot be used together with attribute inline.

13.2.1.6:6 Attribute naked cannot be used together with attribute track_caller.

Undefined Behavior

13.2.1.6:7 It is a safety invariant for the function body to respect the ABI of the function.

13.2.1.6:8 It is a safety invariant for the function body to diverge.

13.2.2. Conditional Compilation Attributes¶

13.2.2.1. Attribute `cfg`¶

Syntax

CfgContent ::=
    cfg ( ConfigurationPredicate )

ConfigurationPredicate ::=
    ConfigurationOption
  | ConfigurationPredicateAll
  | ConfigurationPredicateAny
  | ConfigurationPredicateNot
  | true
  | false

ConfigurationOption ::=
    ConfigurationOptionName ConfigurationOptionValue?

ConfigurationOptionName ::=
    Identifier

ConfigurationOptionValue ::=
    = StringLiteral

ConfigurationPredicateAll ::=
    all ( ConfigurationPredicateList? )

ConfigurationPredicateAny ::=
    any ( ConfigurationPredicateList? )

ConfigurationPredicateNot ::=
    not ( ConfigurationPredicate )

ConfigurationPredicateList ::=
    ConfigurationPredicate (, ConfigurationPredicate)* ,?

Legality Rules

13.2.2.1:1 Attribute cfg enables conditional compilation.

13.2.2.1:2 A configuration predicate is a construct that evaluates statically to either true or false, and controls conditional compilation.

13.2.2.1:3 An all configuration predicate is a configuration predicate that models existential quantifier ALL.

13.2.2.1:4 An all configuration predicate evaluates statically to true when either all nested configuration predicates evaluate to true, or there are no nested configuration predicates.

13.2.2.1:5 An any configuration predicate is a configuration predicate that models existential quantifier ANY.

13.2.2.1:6 An any configuration predicate evaluates statically to true when any nested configuration predicate evaluates to true.

13.2.2.1:7 A not configuration predicate is a configuration predicate that negates the Boolean value of its nested configuration predicate.

13.2.2.1:8 A not configuration predicate evaluates statically to true when its nested configuration predicate evaluates to false.

13.2.2.1:9 Configuration predicate true always evaluates statically to true.

13.2.2.1:10 Configuration predicate false always evaluates statically to false.

13.2.2.1:11 The evaluation of a configuration option is tool-defined.

Examples

#[cfg(all(unix, target_pointer_width = "32"))]
fn on_32bit_unix() {}

13.2.2.2. Attribute `cfg_attr`¶

Syntax

CfgAttrContent ::=
    cfg_attr ( ConfigurationPredicate , AttributeContentList )

Legality Rules

13.2.2.2:1 Attribute cfg_attr enables conditional compilation.

13.2.2.2:2 An attribute cfg_attr where the related configuration predicate evaluates to true is replaced with a new attribute for each AttributeContent enumerated in the attribute's AttributeContentList.

Examples

#[cfg_attr(windows, path="windows.rs")]
mod os;

13.2.3. Derivation Attributes¶

13.2.3.1. Attribute `automatically_derived`¶

Syntax

AutomaticallyDerivedContent ::=
    automatically_derived

Legality Rules

13.2.3.1:1 Attribute automatically_derived is automatically added to implementations that are created by attribute derive for built-in traits.

13.2.3.2. Attribute `derive`¶

Syntax

DeriveContent ::=
    derive ( SimplePathList? )

Legality Rules

13.2.3.2:1 Attribute derive shall apply to abstract data types.

13.2.3.2:2 Attribute derive lists derive macros for automatic implementation by a tool.

Examples

#[derive(PartialEq)]
struct S<T> {
    field: T
}

13.2.3.2:3 Attribute derive causes trait core::cmp::PartialEq to be automatically implemented for struct S<T> as follows:

impl<T: core::cmp::PartialEq> core::cmp::PartialEq for S<T> {
    fn eq(&self, other: &S<T>) -> bool {
       self.field == other.field
    }

    fn ne(&self, other: &S<T>) -> bool {
       self.field != other.field
    }
}

13.2.4. Diagnostics Attributes¶

Note

The contents of this section are informational.

13.2.4:1 Diagnostic attributes are related to linting, and are not defined in this document.

13.2.5. Documentation Attributes¶

13.2.5.1. Attribute `doc`¶

Syntax

DocContent ::=
    doc DocInput

DocInput ::=
    = MacroInvocation
  | = StringLiteral
  | ( TokenTree* )

Legality Rules

13.2.5.1:1 Attribute doc associates documentation with a construct.

Examples

#![doc = "This is a doc comment written as an attribute."]

13.2.6. Foreign Function Interface Attributes¶

13.2.6.1. Attribute `crate_name`¶

Syntax

CrateNameContent ::=
    crate_name = StringLiteral

Legality Rules

13.2.6.1:1 Attribute crate_name shall apply to the crate root module.

13.2.6.1:2 Attribute crate_name shall specify the name of the related crate.

Examples

#![crate_name = "factories"]

13.2.6.2. Attribute `crate_type`¶

Syntax

CrateTypeContent ::=
    crate_type = " CrateType "

CrateType ::=
    bin
  | cdylib
  | dylib
  | lib
  | proc-macro
  | rlib
  | staticlib

Legality Rules

13.2.6.2:1 Attribute crate_type shall apply to the crate root module.

13.2.6.2:2 Attribute crate_type shall specify the linkage type of the crate it appears in.

Examples

#![crate_type = "cdylib"]

13.2.6.3. Attribute `export_name`¶

Syntax

ExportNameContent ::=
    export_name = StringLiteral

Legality Rules

13.2.6.3:1 Attribute export_name shall apply to functions and statics.

13.2.6.3:2 Attribute export_name shall specify the exported symbol of the related function or static.

Examples

#[export_name = "exported_symbol"]
pub fn rust_name() {}

13.2.6.4. Attribute `link`¶

Syntax

LinkContent ::=
    link ( LinkOption )

LinkOption ::=
    NativeLibraryName
  | NativeLibraryNameWithKind
  | WebAssemblyModuleName

NativeLibraryName ::=
    name = StringLiteral

NativeLibraryNameWithKind ::=
    NativeLibraryName , NativeLibraryKind

WebAssemblyModuleName ::=
    wasm_import_module = StringLiteral

NativeLibraryKind ::=
    kind = " NativeLibraryKindType "

NativeLibraryKindType ::=
    dylib
  | raw-dylib
  | framework
  | static

Legality Rules

13.2.6.4:1 Attribute link shall apply to external blocks.

13.2.6.4:2 Attribute link shall specify the name of a native library that a tool should link with.

13.2.6.4:3 The following native library kinds are available:

13.2.6.4:4	Native Library Kind	Description
13.2.6.4:5	dylib	Dynamic library
13.2.6.4:6	raw-dylib	Dynamic library
13.2.6.4:7	framework	macOS framework
13.2.6.4:8	static	Static library

13.2.6.4:9 When attribute link appears without a native library kind, its native library kind defaults to dylib. Native library kind framework is only valid on macOS targets.

13.2.6.4:10 If attribute link appears without a WebAssembly module name, then the WebAssembly module name defaults to env.

13.2.6.4:11 When attribute link appears with raw-dylib as the native library kind, the supplied name must include the file extension.

13.2.6.4:12 When attribute link appears with raw-dylib as the native library kind, the external functions and external statics of the related external block shall not be subject to attribute no_mangle.

Examples

#[link(name = "CoreFoundation", kind = "framework")]
extern {}

13.2.6.5. Attribute `link_name`¶

Syntax

LinkNameContent ::=
    link_name = StringLiteral

Legality Rules

13.2.6.5:1 Attribute link_name shall apply to external functions and external statics.

13.2.6.5:2 Attribute link_name shall specify the linking symbol of the related external function or external static.

13.2.6.5:3 Attribute link_name shall not be applied to external functions and external statics that are annotated with Attribute link_ordinal.

Examples

extern {
    #[link_name = "linking_symbol"]
    pub fn rust_name() {}
}

13.2.6.6. Attribute `link_section`¶

Syntax

LinkSectionContent ::=
    link_section = StringLiteral

Legality Rules

13.2.6.6:1 Attribute link_section shall apply to functions and statics.

13.2.6.6:2 Attribute link_section specifies the object file section where the symbol of the related function or static will be placed.

Examples

#[link_section = ".example_section"]
pub static THE_ANSWER: u32 = 42;

13.2.6.7. Attribute `link_ordinal`¶

Syntax

LinkOrdinalContent ::=
    link_ordinal ( DecimalLiteral )

Legality Rules

13.2.6.7:1 Attribute link_ordinal shall apply to external functions and external statics.

13.2.6.7:2 The related extern block of the external function or external static shall be subject to attribute link with raw-dylib as the native library kind.

13.2.6.7:3 Attribute link_ordinal shall specify the linking symbol of the related external function or external static by ordinal number.

Examples

#[link(name = "lib.dll", kind = "raw-dylib")]
extern "system" {
    #[link_ordinal(16)]
    fn function();
}

13.2.6.8. Attribute `no_link`¶

Syntax

NoLinkContent ::=
    no_link

Legality Rules

13.2.6.8:1 Attribute no_link shall apply to crate imports.

13.2.6.8:2 Attribute no_link indicates that the imported external crate will not be linked into the resulting binary or library.

Examples

#[no_link]
extern crate do_not_link;

13.2.6.9. Attribute `no_main`¶

Syntax

NoMainContent ::=
    no_main

Legality Rules

13.2.6.9:1 Attribute no_main shall apply to the crate root module.

13.2.6.9:2 Attribute no_main indicates that the symbols of the program entry point will not be present in a binary.

Examples

#![no_main]

13.2.6.10. Attribute `no_mangle`¶

Syntax

NoMangleContent ::=
    no_mangle

Legality Rules

13.2.6.10:1 Attribute no_mangle has no effect on constructs other than functions and statics.

13.2.6.10:2 Attribute no_mangle indicates that the name of the related function or static will be used as the symbol for that function or static.

13.2.6.10:3 Attribute no_mangle causes the related function or static to be publicly exported from the produced library or object file.

13.2.6.10:4 An exported function is a function subject to attribute no_mangle.

13.2.6.10:5 An exported static is a static subject to attribute no_mangle.

Examples

#[no_mangle]
pub fn symbol_name() {}

13.2.6.11. Attribute `repr`¶

Syntax

ReprContent ::=
    repr ( Representation )

Representation ::=
    RepresentationKind Alignment?

RepresentationKind ::=
    PrimitiveRepresentation
  | C
  | Rust
  | transparent

Alignment ::=
    AlignmentDecrease
  | AlignmentIncrease

PrimitiveRepresentation ::=
    i8
  | i16
  | i32
  | i64
  | i128
  | isize
  | u8
  | u16
  | u32
  | u64
  | u128
  | usize

AlignmentDecrease ::=
    packed

AlignmentIncrease ::=
    align ( DecimalLiteral )

Legality Rules

13.2.6.11:1 Attribute repr shall apply to abstract data types.

13.2.6.11:2 Attribute repr shall indicate the type representation of the related type.

Examples

#[repr(C, align(8))]
struct c_struct {
    first_field: i16,
    second_field: i8
}

13.2.6.12. Attribute `unsafe`¶

Syntax

UnsafeContent ::=
    unsafe ( BuiltinAttributeContent )

Legality Rules

13.2.6.12:1 Attribute unsafe is used to indicate that an attribute is unsafe.

13.2.6.12:2 Attribute unsafe shall apply to what the contained attribute applies to.

13.2.6.12:3 Attribute unsafe does not affect the behavior of the contained attribute.

13.2.6.12:4 The contained attribute shall be one of the following:

13.2.6.12:5 Attribute no_mangle
13.2.6.12:6 Attribute export_name
13.2.6.12:7 Attribute link_section
13.2.6.12:8 Attribute naked

Examples

#[unsafe(no_mangle)]
pub fn clear_name() {}

13.2.6.13. Attribute `used`¶

Syntax

UsedContent ::=
    used

Legality Rules

13.2.6.13:1 Attribute used shall apply to statics.

13.2.6.13:2 Attribute used forces a tool to keep the related static in the output object file even if the static is not used or referenced by other items in the crate.

Examples

#[used]
pub static THE_ANSWER: u32 = 42;

13.2.7. Limits Attributes¶

13.2.7.1. Attribute `recursion_limit`¶

Syntax

RecursionLimitContent ::=
    recursion_limit = " DecimalLiteral "

Legality Rules

13.2.7.1:1 Attribute recursion_limit shall apply to the crate root module.

13.2.7.1:2 Attribute recursion_limit sets the maximum depth of macro expansion and auto-dereferencing.

Examples

#![recursion_limit = "42"]

13.2.7.2. Attribute `type_length_limit`¶

Syntax

TypeLengthLimitContent ::=
    type_length_limit = " DecimalLiteral "

Legality Rules

13.2.7.2:1 Attribute type_length_limit shall apply to the crate root module.

13.2.7.2:2 Attribute type_length_limit sets the maximum number of generic substitutions for type parameters when constructing a concrete type.

Examples

#![type_length_limit = "42"]

13.2.8. Macros Attributes¶

13.2.8.1. Attribute `collapse_debuginfo`¶

Syntax

CollapseDebuginfoContent ::=
    collapse_debuginfo  ( CollapseDebuginfoKind )

CollapseDebuginfoKind ::=
    no
  | external
  | yes

Legality Rules

13.2.8.1:1 Attribute collapse_debuginfo shall apply to declarative macros.

13.2.8.1:2 Attribute collapse_debuginfo changes the debug location information for the expanded code of the declarative macro to its invocation site. This repeats recursively to the top most expansion of a declarative macro that is not annotated with attribute collapse_debuginfo.

Examples

#[collapse_debuginfo(yes)]
macro_rules! m {
    () => {};
}

13.2.8.2. Attribute `macro_export`¶

Syntax

MacroExportContent ::=
    macro_export

Legality Rules

13.2.8.2:1 Attribute macro_export shall apply to declarative macros.

13.2.8.2:2 Attribute macro_export changes the visibility of the related declarative macro to public visibility and introduces the name of the declarative macro into the item scope of the crate root module.

Examples

#[macro_export]
macro_rules! m {
    () => {};
}

13.2.8.3. Attribute `macro_use`¶

Syntax

MacroUseContent ::=
    macro_use ImportedMacroList?

ImportedMacroList ::=
    ( IdentifierList )

Legality Rules

13.2.8.3:1 Attribute macro_use shall apply to crate imports and modules.

13.2.8.3:2 An ImportedMacroList enumerates macros-to-import. A macro-to-import shall be subject to attribute macro_export.

13.2.8.3:3 When applied to a crate import, attribute macro_use imports from the related crate either:

13.2.8.3:4 The enumerated macros-to-import, or
13.2.8.3:5 If no macros-to-import have been specified, all macros subject to attribute macro_export.

13.2.8.3:6 When applied to a module, attribute macro_use extends the textual macro scope of the related macro.

Examples

#[macro_use(first_macro, second_macro)]
extern crate macros;
#[macro_use]
mod module {}

13.2.8.4. Attribute `proc_macro`¶

Syntax

ProcMacroContent ::=
    proc_macro

Legality Rules

13.2.8.4:1 Attribute proc_macro shall apply to public functions in the crate root module of a proc-macro crate.

13.2.8.4:2 Attribute proc_macro turns the related function into a function-like macro.

Examples

#[proc_macro]
pub fn make_answer_to_life(_items: TokenStream) -> TokenStream {
    "fn answer_to_life() -> u32 { 42 }".parse().unwrap()
}

13.2.8.5. Attribute `proc_macro_attribute`¶

ProcMacroAttributeContent ::=
    proc_macro_attribute

Legality Rules

13.2.8.5:1 Attribute proc_macro_attribute shall apply to public functions in the crate root module of a proc-macro crate.

13.2.8.5:2 Attribute proc_macro_attribute turns the related function into an attribute macro.

Examples

#[proc_macro_attribute]
pub fn output_and_return_item
    (attr: TokenStream, item: TokenStream) -> TokenStream
{
    println!("attr: \"{}\"", attr.to_string());
    println!("item: \"{}\"", item.to_string());
    item
}

13.2.8.6. Attribute `proc_macro_derive`¶

Syntax

ProcMacroDeriveContent ::=
    proc_macro_derive ( DeriveName (, HelperAttributeList)? )

DeriveName ::=
    Name

HelperAttributeList ::=
    attributes ( IdentifierList )

Legality Rules

13.2.8.6:1 Attribute proc_macro_derive shall apply to public functions in the crate root module of a proc-macro crate.

13.2.8.6:2 Attribute proc_macro_derive turns the related function into a derive macro, where DeriveName defines the name of the derive macro available to attribute derive.

13.2.8.6:3 The HelperAttributeList declares the derive helper attributes of the derive macro.

Examples

#[proc_macro_derive(Answer, attributes(marker))]
pub fn derive_answer_to_life(_items: TokenStream) -> TokenStream {
    "fn answer_to_life() -> u32 { 42 }".parse().unwrap()
}

#[derive(Answer)]
struct S {
    #[marker] field: ()
}

13.2.9. Modules Attributes¶

13.2.9.1. Attribute `path`¶

Syntax

PathContent ::=
    path = StringLiteral

Legality Rules

13.2.9.1:1 Attribute path shall apply to modules.

13.2.9.1:2 Attribute path specifies the module path of the respective module as a string literal.

13.2.9.1:3 A tool is free to define the format of a module path.

Examples

#[path = "path/to/inline_module"]
mod inline_module {
    #[path = "path/to/outline_module"]
    mod outline_module;
}

13.2.10. Prelude Attributes¶

13.2.10.1. Attribute `no_implicit_prelude`¶

Syntax

NoImplicitPreludeContent ::=
    no_implicit_prelude

Legality Rules

13.2.10.1:1 The inner attribute version of attribute no_implicit_prelude shall apply to the crate root module or to modules.

13.2.10.1:2 The outer attribute version of attribute no_implicit_prelude shall apply to modules.

13.2.10.1:3 Attribute no_implicit_prelude prevents the import of the external prelude, the standard library prelude, and the tool prelude.

Examples

#[no_implicit_prelude]
mod module {}

13.2.10.2. Attribute `no_std`¶

Syntax

NoStdContent ::=
    no_std

Legality Rules

13.2.10.2:1 Attribute no_std shall apply to the crate root module.

13.2.10.2:2 Attribute no_std has the following effects:

13.2.10.2:3 Prevents the import of the standard library prelude.
13.2.10.2:4 Imports the core prelude.
13.2.10.2:5 Imports all declarative macros subject to attribute macro_export of the core crate into the macro_use prelude.

Examples

#![no_std]

13.2.11. Runtime Attributes¶

13.2.11.1. Attribute `global_allocator`¶

Syntax

GlobalAllocatorContent ::=
    global_allocator

Legality Rules

13.2.11.1:1 Attribute global_allocator shall apply to statics whose types implement the core::alloc::GlobalAlloc trait.

13.2.11.1:2 Attribute global_allocator sets the global allocator to the related static.

Examples

#[global_allocator]
pub static THE_ANSWER: u32 = 42;

13.2.11.2. Attribute `panic_handler`¶

Syntax

PanicHandlerContent ::=
    panic_handler

Legality Rules

13.2.11.2:1 Attribute panic_handler shall apply to functions with the following restrictions:

13.2.11.2:2 It lacks function qualifiers,
13.2.11.2:3 Its ABI is Rust,
13.2.11.2:4 It lacks generic parameters,
13.2.11.2:5 It has a single function parameter whose type is & core::panic::PanicInfo,
13.2.11.2:6 It has the never type as its return type,
13.2.11.2:7 It lacks a where clause,
13.2.11.2:8 It has a function body.

13.2.11.2:9 Attribute panic_handler indicates that its related function defines the behavior of panics.

13.2.11.2:10 A crate graph shall contain exactly one function subject to attribute panic_handler.

Examples

#[panic_handler]
fn panic(info: &core::panic::PanicInfo) -> ! {}

13.2.11.3. Attribute `windows_subsystem`¶

Syntax

WindowsSubsystemContent ::=
    windows_subsystem = " SubsystemKind "

SubsystemKind ::=
    console
  | windows

Legality Rules

13.2.11.3:1 Attribute windows_subsystem shall apply to the crate root module of a binary crate.

13.2.11.3:2 Attribute windows_subsystem specifies the subsystem on Windows.

13.2.11.3:3 If attribute windows_subsystem is missing, the subsystem of the related binary crate defaults to console.

Examples

#![windows_subsystem = "console"]

13.2.12. Testing Attributes¶

13.2.12.1. Attribute `ignore`¶

Syntax

IgnoreContent ::=
    ignore IgnoreReason?

IgnoreReason ::=
    = StringLiteral

Legality Rules

13.2.12.1:1 Attribute ignore shall apply to testing functions.

13.2.12.1:2 Attribute ignore prevents the execution of its related testing function.

Examples

#[test]
#[ignore = "not implemented yet"]
fn unit_testing_function() {}

13.2.12.2. Attribute `should_panic`¶

Syntax

ShouldPanicContent ::=
    should_panic ExpectedPanicMessage?

ExpectedPanicMessage ::=
    ( expected = StringLiteral )

Legality Rules

13.2.12.2:1 Attribute should_panic shall apply to testing functions.

13.2.12.2:2 Attribute should_panic indicates that for the related testing function to pass, it should panic.

13.2.12.2:3 If ExpectedPanicMessage is specified, then the related testing function passes only when the panic message contains the ExpectedPanicMessage.

Examples

#[test]
#[should_panic(expected = "did not get meaning of life")]
fn test_meaning_of_life() {
    assert_eq!(meaning_of_life(), 42, "did not get meaning of life");
}

13.2.12.3. Attribute `test`¶

Syntax

TestContent ::=
    test

Legality Rules

13.2.12.3:1 Attribute test shall apply to functions that:

13.2.12.3:2 Is not an async function, and
13.2.12.3:3 Is not an unsafe function, and
13.2.12.3:4 Lacks generic parameters, and
13.2.12.3:5 Lacks function parameters, and

13.2.12.3:6 Attribute test indicates that the respective function is a testing function.

13.2.12.3:7 A testing function that returns the unit type passes when it terminates and does not panic.

13.2.12.3:8 A testing function that returns core::result::Result<(), E> passes when it returns core::result::Result::Ok(()).

13.2.12.3:9 A testing function that does not terminate shall pass and fail according to the tool.

Examples

#[test]
fn test_the_thing() -> core::result::Result<()> {
    let input = create_input()?;
    do_the_thing(&input)?;
    core::result::Result::Ok(());
}

13.2.13. Type Attributes¶

13.2.13.1. Attribute `non_exhaustive`¶

Syntax

NonExhaustiveContent ::=
    non_exhaustive

Legality Rules

13.2.13.1:1 Attribute non_exhaustive shall apply to enum types, enum variants, and struct types.

13.2.13.1:2 Attribute non_exhaustive indicates that the related abstract data type or enum variant may have more fields or enum variants added in the future. A type subject to attribute non_exhaustive is referred to as a non-exhaustive type.

13.2.13.1:3 A non-exhaustive type shall not be constructed outside of its defining crate.

13.2.13.1:4 An enum variant subject to attribute non_exhaustive is referred to as a non-exhaustive variant.

13.2.13.1:5 A non-exhaustive variant shall not be constructed outside of its defining crate.

13.2.13.1:6 Pattern matching a non-exhaustive variant shall require a struct pattern with a rest pattern outside its defining crate.

13.2.13.1:7 Pattern matching a non-exhaustive variant does not contribute towards the exhaustiveness of match arms.

Examples

#[non_exhaustive]
enum enum_with_future_variants {
    Variant
}

enum enum_variants_with_future_fields {
    #[non_exhaustive] Send { from: u32, to: u32 },
    #[non_exhaustive] Quit
}

#[non_exhaustive]
struct struct_with_future_fields {
    field: u32
}

13. Attributes¶

13.1. Attribute Properties¶

13.2. Built-in Attributes¶

13.2.1. Code Generation Attributes¶

13.2.1.1. Attribute cold¶

13.2.1.2. Attribute inline¶

13.2.1.3. Attribute no_builtins¶

13.2.1.4. Attribute target_feature¶

13.2.1.5. Attribute track_caller¶

13.2.1.6. Attribute naked¶

13.2.2. Conditional Compilation Attributes¶

13.2.2.1. Attribute cfg¶

13.2.2.2. Attribute cfg_attr¶

13.2.3. Derivation Attributes¶

13.2.3.1. Attribute automatically_derived¶

13.2.3.2. Attribute derive¶

13.2.4. Diagnostics Attributes¶

13.2.5. Documentation Attributes¶

13.2.5.1. Attribute doc¶

13.2.6. Foreign Function Interface Attributes¶

13.2.6.1. Attribute crate_name¶

13.2.6.2. Attribute crate_type¶

13.2.6.3. Attribute export_name¶

13.2.6.4. Attribute link¶

13.2.6.5. Attribute link_name¶

13.2.6.6. Attribute link_section¶

13.2.6.7. Attribute link_ordinal¶

13.2.6.8. Attribute no_link¶

13.2.6.9. Attribute no_main¶

13.2.6.10. Attribute no_mangle¶

13.2.6.11. Attribute repr¶

13.2.6.12. Attribute unsafe¶

13.2.6.13. Attribute used¶

13.2.7. Limits Attributes¶

13.2.7.1. Attribute recursion_limit¶

13.2.7.2. Attribute type_length_limit¶

13.2.8. Macros Attributes¶

13.2.8.1. Attribute collapse_debuginfo¶

13.2.8.2. Attribute macro_export¶

13.2.8.3. Attribute macro_use¶

13.2.8.4. Attribute proc_macro¶

13.2.8.5. Attribute proc_macro_attribute¶

13.2.8.6. Attribute proc_macro_derive¶

13.2.9. Modules Attributes¶

13.2.9.1. Attribute path¶

13.2.10. Prelude Attributes¶

13.2.10.1. Attribute no_implicit_prelude¶

13.2.10.2. Attribute no_std¶

13.2.11. Runtime Attributes¶

13.2.11.1. Attribute global_allocator¶

13.2.11.2. Attribute panic_handler¶

13.2.11.3. Attribute windows_subsystem¶

13.2.12. Testing Attributes¶

13.2.12.1. Attribute ignore¶

13.2.12.2. Attribute should_panic¶

13.2.12.3. Attribute test¶

13.2.13. Type Attributes¶

13.2.13.1. Attribute non_exhaustive¶

13.2.1.1. Attribute `cold`¶

13.2.1.2. Attribute `inline`¶

13.2.1.3. Attribute `no_builtins`¶

13.2.1.4. Attribute `target_feature`¶

13.2.1.5. Attribute `track_caller`¶

13.2.1.6. Attribute `naked`¶

13.2.2.1. Attribute `cfg`¶

13.2.2.2. Attribute `cfg_attr`¶

13.2.3.1. Attribute `automatically_derived`¶

13.2.3.2. Attribute `derive`¶

13.2.5.1. Attribute `doc`¶

13.2.6.1. Attribute `crate_name`¶

13.2.6.2. Attribute `crate_type`¶

13.2.6.3. Attribute `export_name`¶

13.2.6.4. Attribute `link`¶

13.2.6.5. Attribute `link_name`¶

13.2.6.6. Attribute `link_section`¶

13.2.6.7. Attribute `link_ordinal`¶

13.2.6.8. Attribute `no_link`¶

13.2.6.9. Attribute `no_main`¶

13.2.6.10. Attribute `no_mangle`¶

13.2.6.11. Attribute `repr`¶

13.2.6.12. Attribute `unsafe`¶

13.2.6.13. Attribute `used`¶

13.2.7.1. Attribute `recursion_limit`¶

13.2.7.2. Attribute `type_length_limit`¶

13.2.8.1. Attribute `collapse_debuginfo`¶

13.2.8.2. Attribute `macro_export`¶

13.2.8.3. Attribute `macro_use`¶

13.2.8.4. Attribute `proc_macro`¶

13.2.8.5. Attribute `proc_macro_attribute`¶

13.2.8.6. Attribute `proc_macro_derive`¶

13.2.9.1. Attribute `path`¶

13.2.10.1. Attribute `no_implicit_prelude`¶

13.2.10.2. Attribute `no_std`¶

13.2.11.1. Attribute `global_allocator`¶

13.2.11.2. Attribute `panic_handler`¶

13.2.11.3. Attribute `windows_subsystem`¶

13.2.12.1. Attribute `ignore`¶

13.2.12.2. Attribute `should_panic`¶

13.2.12.3. Attribute `test`¶

13.2.13.1. Attribute `non_exhaustive`¶