Caution
You’re reading a draft of the Ferrocene Language Specification. Some parts of this document might be missing, incomplete or incorrect. Our aim is to have the specification ready by the end of 2022.
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:4 Attribute macros.
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
|ColdContent
|CrateNameContent
|CrateTypeContent
|DeriveContent
|DocContent
|ExportNameContent
|GlobalAllocatorContent
|InlineContent
|IgnoreContent
|LinkContent
|LinkNameContent
|LinkSectionContent
|MacroExportContent
|MacroUseContent
|NoBinutilsContent
|NoImplicitPreludeContent
|NoLinkContent
|NoMainContent
|NoMangleContent
|NonExhaustiveContent
|NoStdContent
|PanicHandlerContent
|PathContent
|ProcMacroAttributeContent
|ProcMacroContent
|ProcMacroDeriveContent
|RecursionLimitContent
|ReprContent
|ShouldPanicContent
|TargetFeatureContent
|TestContent
|TrackCallerContent
|TypeLengthLimitContent
|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:5 Attribute
no_builtins
.13.2:6 Attribute
target_feature
.13.2:7 Attribute
track_caller
.
13.2:8 The following built-in attributes are conditional compilation attributes:
13.2:11 The following built-in attributes are derivation attributes:
13.2:12 Attribute
automatically_derived
.
13.2:14 The following built-in attributes are diagnostics attributes:
13.2:15 Attribute
allow
.13.2:16 Attribute
deny
.13.2:17 Attribute
deprecated
.13.2:18 Attribute
forbid
.13.2:19 Attribute
must_use
.13.2:20 Attribute
warn
.
13.2:21 The following built-in attributes are documentation attributes:
13.2:23 The following built-in attributes are foreign function interface attributes:
13.2:24 Attribute
crate_name
.13.2:25 Attribute
crate_type
.13.2:26 Attribute
export_name
.13.2:29 Attribute
link_section
.
13.2:35 The following built-in attributes are limits attributes:
13.2:36 Attribute
recursion_limit
.13.2:37 Attribute
type_length_limit
.
13.2:38 The following built-in attributes are macro attributes:
13.2:39 Attribute
macro_export
.13.2:41 Attribute
proc_macro
.13.2:42 Attribute
proc_macro_attribute
.13.2:43 Attribute
proc_macro_derive
.
13.2:44 The following built-in attributes are modules attributes:
13.2:46 The following built-in attributes are prelude attributes:
13.2:47 Attribute
no_implicit_prelude
.
13.2:49 The following built-in attributes are runtime attributes:
13.2:50 Attribute
global_allocator
.13.2:51 Attribute
panic_handler
.13.2:52 Attribute
windows_subsystem
.
13.2:53 The following built-in attributes are testing attributes:
13.2:57 The following built-in attributes are type attributes:
13.2:58 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
::= inlineInlineHint
?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:
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 |
bmi1 |
Bit Manipulation Instruction Sets |
|
13.2.1.4:10 |
bmi2 |
Bit Manipulation Instruction Sets 2 |
|
13.2.1.4:11 |
fma |
avx |
Three-operand fused multiply-add |
13.2.1.4:12 |
fxsr |
Save and restore x87 FPU, MMX technology, and SSE state |
|
13.2.1.4:13 |
lzcnt |
Leading zeros count |
|
13.2.1.4:14 |
pclmulqdq |
sse2 |
Packed carry-less multiplication quadword |
13.2.1.4:15 |
popcnt |
Count of bits set to 1 |
|
13.2.1.4:16 |
rdrand |
Read random number |
|
13.2.1.4:17 |
rdseed |
Read random seed |
|
13.2.1.4:18 |
sha |
sse2 |
Secure Hash Algorithm |
13.2.1.4:19 |
sse |
Streaming SIMD Extensions |
|
13.2.1.4:20 |
sse2 |
sse |
Streaming SIMD Extensions 2 |
13.2.1.4:21 |
sse3 |
sse2 |
Streaming SIMD Extensions 3 |
13.2.1.4:22 |
sse4.1 |
sse3 |
Streaming SIMD Extensions 4.1 |
13.2.1.4:23 |
sse4.2. |
sse4.1 |
Streaming SIMD Extensions 4.2 |
13.2.1.4:24 |
ssse3 |
sse3 |
Supplemental Streaming SIMD Extensions 3 |
13.2.1.4:25 |
xsave |
Save processor extended status |
|
13.2.1.4:26 |
xsavec |
Save processor extended status with compaction |
|
13.2.1.4:27 |
xsaveopt |
Save processor extended states optimized |
|
13.2.1.4:28 |
xsaves |
Save processor extended states supervizor |
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. Conditional Compilation Attributes¶
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. 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
::= docDocInput
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
,NativeLibrayKind
WebAssemblyModuleName
::= wasm_import_module =StringLiteral
NativeLibrayKind
::= kind = "NativeLibrayKindType
"NativeLibrayKindType
::= 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 |
framework |
macOS framework |
13.2.6.4:7 |
static |
Static library |
13.2.6.4:8
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:9
If attribute link
appears without a WebAssembly module name, then the
WebAssembly module name defaults to env
.
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.
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 no_link
¶
Syntax
NoLinkContent
::=
no_link
Legality Rules
13.2.6.7:1
Attribute no_link
shall apply to crate imports.
13.2.6.7: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.8. Attribute no_main
¶
Syntax
NoMainContent
::=
no_main
Legality Rules
13.2.6.8:1
Attribute no_main
shall apply to the crate root module.
13.2.6.8: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.9. Attribute no_mangle
¶
Syntax
NoMangleContent
::=
no_mangle
Legality Rules
13.2.6.9:1
Attribute no_mangle
has no effect on constructs other than
functions and statics.
13.2.6.9: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.9:3
Attribute no_mangle
causes the related function or static to
be publicly exported from the produced library or object file.
13.2.6.9:4
An exported function is a function subject to attribute
no_mangle
.
13.2.6.9:5
An exported static is a static subject to attribute
no_mangle
.
Examples
#[no_mangle]
pub fn symbol_name() {}
13.2.6.10. Attribute repr
¶
Syntax
ReprContent
::= repr (Representation
)Representation
::=RepresentationKind
Alignment
?RepresentationKind
::=PrimitiveRepresentation
| C | transparentAlignment
::=AlignmentDecrease
|AlignmentIncrease
PrimitiveRepresentation
::= i8 | i16 | i32 | i64 | i128 | isize | u8 | u16 | u32 | u64 | u128 | usizeAlignmentDecrease
::= packed (DecimalLiteral
)AlignmentIncrease
::= align (DecimalLiteral
)
Legality Rules
13.2.6.10:1
Attribute repr
shall apply to abstract data types.
13.2.6.10: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.11. Attribute used
¶
Syntax
UsedContent
::=
used
Legality Rules
13.2.6.11:1
Attribute used
shall apply to statics.
13.2.6.11: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 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_useImportedMacroList
?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. 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 thecore
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
::= ignoreIgnoreReason
?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_panicExpectedPanicMessage
?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. 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
}