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
  | bmi1
  | bmi2
  | fma
  | fxsr
  | lzcnt
  | pclmulqdq
  | popcnt
  | rdrand
  | rdseed
  | sha
  | sse
  | sse2
  | sse3
  | sse4.1
  | sse4.2
  | ssse3
  | xsave
  | xsavec
  | xsaveopt
  | xsaves

Legality Rules

13.2.1.4:1 Attribute target_feature shall apply to unsafe functions.

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:

Undefined Behavior

13.2.1.4:29 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.2.1. Attribute cfg¶

Syntax

CfgContent ::=
    cfg ( ConfigurationPredicate )

ConfigurationPredicate ::=
    ConfigurationOption
  | ConfigurationPredicateAll
  | ConfigurationPredicateAny
  | ConfigurationPredicateNot

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 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.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.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.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 , NativeLibrayKind

WebAssemblyModuleName ::=
    wasm_import_module = StringLiteral

NativeLibrayKind ::=
    kind = " NativeLibrayKindType "

NativeLibrayKindType ::=
    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: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 main function 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
  | 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 used¶

Syntax

UsedContent ::=
    used

Legality Rules

13.2.6.12:1 Attribute used shall apply to statics.

13.2.6.12: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.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.1. Attribute macro_export¶

Syntax

MacroExportContent ::=
    macro_export

Legality Rules

13.2.8.1:1 Attribute macro_export shall apply to declarative macros.

13.2.8.1: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.2. Attribute macro_use¶

Syntax

MacroUseContent ::=
    macro_use ImportedMacroList?

ImportedMacroList ::=
    ( IdentifierList )

Legality Rules

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

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

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

• 13.2.8.2:4 The enumerated macros-to-import, or

• 13.2.8.2:5 If no macros-to-import have been specified, all macros subject to attribute macro_export.

13.2.8.2: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.3. Attribute proc_macro¶

Syntax

ProcMacroContent ::=
    proc_macro

Legality Rules

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

13.2.8.3: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.4. Attribute proc_macro_attribute¶

ProcMacroAttributeContent ::=
    proc_macro_attribute

Legality Rules

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

13.2.8.4: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.5. Attribute proc_macro_derive¶

Syntax

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

DeriveName ::=
    Name

HelperAttributeList ::=
    attributes ( IdentifierList )

Legality Rules

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

13.2.8.5: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.5: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.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.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.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.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 Its return type is the unit type.

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

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

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

13.2.12.3:10 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.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
}