Doc attributes

The many uses of attributes

Note: This page has not been updated in a long time. There are many more attributes in use now. A complete list of attributes is available from https://github.com/mozilla/rust/blob/master/src/librustc/middle/lint.rs in the items "crate_attrs" and "other_attrs".

Meta items

Attributes are built from meta items, which have three forms:

• the simple word meta item, which is just an identifier, as in test
• the name-value meta item, an ident/literal pair, as in target_os = "win32"
• the list meta item, a named list of additional meta items, as in names(fred, barney, wilma)

In name-value items the literal may be any Rust literal type, though strings are seen most often. Meta items may nest arbitrarily: args(yes, count = 10, names(fred, barny, wilma))

Attributes

The primary use of meta items is for applying attributes to items, crates, methods, fields, and potentially other bits of code. Attributes provide additional information to the compiler and may also be accessed via reflection at runtime. An attribute is simply a meta item wrapped in attribute syntax - a preceding hash sigil and enclosing brackets:

#[test]

or

#[cfg(target_os = "linux")]

Any number of items may precede the definition of an item (or native item):

#[test]
#[cfg(target_os = "linux")]
mod m { ... }

Additionally, attributes may be applied by placing them immediately inside the openining brace of certain items, and terminating each with a semi-colon:

mod m {
    #[test];
    ...
}

Similarly, to apply attributes to a crate, they should be specified at the beginning of a crate file, each terminated with a semicolon.

Crate Linkage Attributes

A crate's name and version are determined by the crate_id attribute, which is a name-value meta item containing a string like "my_crate#0.5". This metadata can, in turn, be used in providing a string RHS to the extern mod keyword.

An example of a typical crate link attribute and various ways of linking to another crate:

#[crate_id = "std#0.10-pre"];

extern mod std;
extern mod std010 = "std#0.10-pre";
extern mod std_anyversion = "std";

Build Configuration

Each time the compiler is run, it defines a set of meta items describing the compilation environment, called the build configuration. Several meta items are defined by default while others may be user-defined. The default items are:

• target_os - A name/value item with the value set to a string representing the target operating system, either "linux", "macos", or "win32".
• target_arch - A name/value item with the value set to a string representing the target architecture, currently always "x86".
• target_libc - A name/value item with the value set to a string naming the libc dynamic library.
• build_compiler - A name/value item with the value set to the name of the compiler.
• windows - A word item that is defined when building for Windows
• unix - A word item that is defined when building for Linux, OS X, or FreeBSD

Conditional Compilation

The build configuration can be used to conditionally compile items, using the cfg attribute. The cfg attribute is a list meta item containing a meta item that is compared to all meta items in the build configuration. If any match is found the item is compiled; if no match is found the item is parsed but not compiled.

An example of using conditional compilation to build different methods on different platforms:

#[cfg(unix)]
fn f() { ... }

#[cfg(target_arch = "x86")]
fn f() { ... }

Unit testing

Rust includes a built-in unit testing facility which makes use of attributes and conditional compilation.

Other crate attributes

// Tell the compiler to output a library by default
#[crate_type = "lib"];

// Don't link to std by default
#[no_std];

Both of these are just informational, and no tool actually uses them yet.

// A very short description of the crate
#[comment = "The Rust standard library"];
#[license = "MIT/ASL2"];

Rustdoc

[Rustdocs](Doc using Rustdoc) are usually provided in documentation comments, but this is just sugar for doc attributes.

/// Description
fn oof() { }

#[doc = "Description"]
fn rab() { }

Control compiler warnings

Compiler warnings and errors can be controlled to a very fine level with attributes.

// I don't want to see any camel cased types
#[deny(non_camel_case_types)]
mod {
    type Foo = Bar;
    // Oh, but just this once
    #[allow(non_camel_case_types)]
    type baz = Foo;
    // No, I'm serious. I'm going to completely forbid those camel case
    // shenanigans so they can't be turned back on
    #[forbid(non_camel_case_types)]
    mod quux {
        ...
    }
}

Also, warn works too. The complete list of possible lint checks can be requested from rustc on the command line by running rustc -W help.

Foreign functions

// Specify the calling convention used by foreign code
#[abi = "cdecl"] extern { ... }
#[abi = "stdcall"] extern { ... }

// Don't try to link this library automatically
#[nolink] extern mod foo { }

Inlining

#[inline] fn foo() { }
#[inline(always)] fn bar() { }
#[inline(never)] fn baz() { }

Overriding the path to module files

// Load our raygun module from flowerpot.rs instead of raygun.rs
#[path = "flowerpot.rs"]
mod raygun;

Auto-serialization

The auto_encode and auto_decode attributes can be used to automatically generate serializers for types.

Main

A function annotated with #[main] will be treated as the main function, overriding any other function named main.

Relationship with macros

Please see Bikeshed syntax extension