.RS File Format – Attributes

Syntax

InnerAttribute: # ! [ Attr ]
OuterAttribute: # [ Attr ]

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

AttrInput:
      DelimTokenTree
    | = Expression

• Outer attributes (#[…]) apply to the form that follows.
• Inner attributes (#![…]) apply to the form they are declared within, such as a module or crate.
• Active attributes remove themselves from the form they are on during processing. cfg, cfg_attr and attribute macros are active; all others are inert.
• Tool attributes such as #[rustfmt::skip] and #[clippy::…] are for external tools.

#![allow(unused)]             // inner: the whole module

#[derive(Debug, Clone)]       // outer: the following struct
pub struct Point { x: i32, y: i32 }

#[inline]
#[must_use = "this returns a new value"]
pub fn twice(x: i32) -> i32 { x * 2 }

#[cfg(test)]
mod tests {
    #[test]
    fn it_works() {
        assert_eq!(super::twice(2), 4);
    }
}

#[unsafe(no_mangle)]
pub extern "C" fn entry() {}

Built-in attributes

Conditional compilation

ConfigurationPredicate:
    ConfigurationOption | ConfigurationAll | ConfigurationAny | ConfigurationNot | true | false

ConfigurationOption: IDENTIFIER ( = ( STRING_LITERAL | RAW_STRING_LITERAL ) )?
ConfigurationAll:    all ( ConfigurationPredicateList? )
ConfigurationAny:    any ( ConfigurationPredicateList? )
ConfigurationNot:    not ( ConfigurationPredicate )

A predicate evaluates to true or false using options set when the crate is compiled. all() is true when empty; any() is false when empty. Code inside the crate cannot set options; rustc --print cfg --target TARGET lists them for a target.

feature = "name" is a Cargo convention for optional features and is not defined by the compiler.

#[cfg(target_os = "linux")]
fn only_on_linux() {}

#[cfg(all(unix, target_pointer_width = "64"))]
fn on_64bit_unix() {}

#[cfg(not(feature = "std"))]
extern crate core as std;

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

let kind = if cfg!(unix) { "unix" } else { "other" };

derive

#[derive(…)] calls derive macros, which generate items, usually trait implementations, for a struct, enum or union. It may be repeated, and all the listed macros are invoked. The compiler’s built-in derives are Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq and PartialOrd.

Each type parameter normally gets a bound on the derived trait, and each field is handled by that trait. Default can be derived on an enum if one unit variant is marked #[default].

#[derive(PartialEq, Clone)]
struct Foo<T> {
    a: i32,
    b: T,
}

// The PartialEq derive generates, in effect:
impl<T: PartialEq> PartialEq for Foo<T> {
    fn eq(&self, other: &Foo<T>) -> bool {
        self.a == other.a && self.b == other.b
    }
}

Other crates can provide derive macros, as serde does. See Procedural macros.