<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Attributes - The Rust Reference</title>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<base href="">
<link rel="stylesheet" href="book.css">
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel="stylesheet" type="text/css">
<link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500" rel="stylesheet" type="text/css">
<link rel="shortcut icon" href="favicon.png">
<!-- Font Awesome -->
<link rel="stylesheet" href="_FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
<link rel="stylesheet" href="src/theme/reference.css">
</head>
<body class="light">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = 'light'; }
document.body.className = theme;
document.querySelector('html').className = theme + ' js';
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<ol class="chapter"><li class="affix"><a href="introduction.html">Introduction</a></li><li><a href="notation.html"><strong aria-hidden="true">1.</strong> Notation</a></li><li><a href="lexical-structure.html"><strong aria-hidden="true">2.</strong> Lexical structure</a></li><li><ol class="section"><li><a href="input-format.html"><strong aria-hidden="true">2.1.</strong> Input format</a></li><li><a href="keywords.html"><strong aria-hidden="true">2.2.</strong> Keywords</a></li><li><a href="identifiers.html"><strong aria-hidden="true">2.3.</strong> Identifiers</a></li><li><a href="comments.html"><strong aria-hidden="true">2.4.</strong> Comments</a></li><li><a href="whitespace.html"><strong aria-hidden="true">2.5.</strong> Whitespace</a></li><li><a href="tokens.html"><strong aria-hidden="true">2.6.</strong> Tokens</a></li><li><a href="paths.html"><strong aria-hidden="true">2.7.</strong> Paths</a></li></ol></li><li><a href="macros.html"><strong aria-hidden="true">3.</strong> Macros</a></li><li><ol class="section"><li><a href="macros-by-example.html"><strong aria-hidden="true">3.1.</strong> Macros By Example</a></li><li><a href="procedural-macros.html"><strong aria-hidden="true">3.2.</strong> Procedural Macros</a></li></ol></li><li><a href="crates-and-source-files.html"><strong aria-hidden="true">4.</strong> Crates and source files</a></li><li><a href="items-and-attributes.html"><strong aria-hidden="true">5.</strong> Items and attributes</a></li><li><ol class="section"><li><a href="items.html"><strong aria-hidden="true">5.1.</strong> Items</a></li><li><ol class="section"><li><a href="items/modules.html"><strong aria-hidden="true">5.1.1.</strong> Modules</a></li><li><a href="items/extern-crates.html"><strong aria-hidden="true">5.1.2.</strong> Extern crates</a></li><li><a href="items/use-declarations.html"><strong aria-hidden="true">5.1.3.</strong> Use declarations</a></li><li><a href="items/functions.html"><strong aria-hidden="true">5.1.4.</strong> Functions</a></li><li><a href="items/type-aliases.html"><strong aria-hidden="true">5.1.5.</strong> Type aliases</a></li><li><a href="items/structs.html"><strong aria-hidden="true">5.1.6.</strong> Structs</a></li><li><a href="items/enumerations.html"><strong aria-hidden="true">5.1.7.</strong> Enumerations</a></li><li><a href="items/unions.html"><strong aria-hidden="true">5.1.8.</strong> Unions</a></li><li><a href="items/constant-items.html"><strong aria-hidden="true">5.1.9.</strong> Constant items</a></li><li><a href="items/static-items.html"><strong aria-hidden="true">5.1.10.</strong> Static items</a></li><li><a href="items/traits.html"><strong aria-hidden="true">5.1.11.</strong> Traits</a></li><li><a href="items/implementations.html"><strong aria-hidden="true">5.1.12.</strong> Implementations</a></li><li><a href="items/external-blocks.html"><strong aria-hidden="true">5.1.13.</strong> External blocks</a></li></ol></li><li><a href="items/generics.html"><strong aria-hidden="true">5.2.</strong> Type and lifetime parameters</a></li><li><a href="items/associated-items.html"><strong aria-hidden="true">5.3.</strong> Associated Items</a></li><li><a href="visibility-and-privacy.html"><strong aria-hidden="true">5.4.</strong> Visibility and Privacy</a></li><li><a href="attributes.html" class="active"><strong aria-hidden="true">5.5.</strong> Attributes</a></li></ol></li><li><a href="statements-and-expressions.html"><strong aria-hidden="true">6.</strong> Statements and expressions</a></li><li><ol class="section"><li><a href="statements.html"><strong aria-hidden="true">6.1.</strong> Statements</a></li><li><a href="expressions.html"><strong aria-hidden="true">6.2.</strong> Expressions</a></li><li><ol class="section"><li><a href="expressions/literal-expr.html"><strong aria-hidden="true">6.2.1.</strong> Literal expressions</a></li><li><a href="expressions/path-expr.html"><strong aria-hidden="true">6.2.2.</strong> Path expressions</a></li><li><a href="expressions/block-expr.html"><strong aria-hidden="true">6.2.3.</strong> Block expressions</a></li><li><a href="expressions/operator-expr.html"><strong aria-hidden="true">6.2.4.</strong> Operator expressions</a></li><li><a href="expressions/grouped-expr.html"><strong aria-hidden="true">6.2.5.</strong> Grouped expressions</a></li><li><a href="expressions/array-expr.html"><strong aria-hidden="true">6.2.6.</strong> Array and index expressions</a></li><li><a href="expressions/tuple-expr.html"><strong aria-hidden="true">6.2.7.</strong> Tuple and index expressions</a></li><li><a href="expressions/struct-expr.html"><strong aria-hidden="true">6.2.8.</strong> Struct expressions</a></li><li><a href="expressions/enum-variant-expr.html"><strong aria-hidden="true">6.2.9.</strong> Enum variant expressions</a></li><li><a href="expressions/call-expr.html"><strong aria-hidden="true">6.2.10.</strong> Call expressions</a></li><li><a href="expressions/method-call-expr.html"><strong aria-hidden="true">6.2.11.</strong> Method call expressions</a></li><li><a href="expressions/field-expr.html"><strong aria-hidden="true">6.2.12.</strong> Field access expressions</a></li><li><a href="expressions/closure-expr.html"><strong aria-hidden="true">6.2.13.</strong> Closure expressions</a></li><li><a href="expressions/loop-expr.html"><strong aria-hidden="true">6.2.14.</strong> Loop expressions</a></li><li><a href="expressions/range-expr.html"><strong aria-hidden="true">6.2.15.</strong> Range expressions</a></li><li><a href="expressions/if-expr.html"><strong aria-hidden="true">6.2.16.</strong> If and if let expressions</a></li><li><a href="expressions/match-expr.html"><strong aria-hidden="true">6.2.17.</strong> Match expressions</a></li><li><a href="expressions/return-expr.html"><strong aria-hidden="true">6.2.18.</strong> Return expressions</a></li></ol></li></ol></li><li><a href="type-system.html"><strong aria-hidden="true">7.</strong> Type system</a></li><li><ol class="section"><li><a href="types.html"><strong aria-hidden="true">7.1.</strong> Types</a></li><li><a href="dynamically-sized-types.html"><strong aria-hidden="true">7.2.</strong> Dynamically Sized Types</a></li><li><a href="type-layout.html"><strong aria-hidden="true">7.3.</strong> Type layout</a></li><li><a href="interior-mutability.html"><strong aria-hidden="true">7.4.</strong> Interior mutability</a></li><li><a href="subtyping.html"><strong aria-hidden="true">7.5.</strong> Subtyping and Variance</a></li><li><a href="trait-bounds.html"><strong aria-hidden="true">7.6.</strong> Trait and lifetime bounds</a></li><li><a href="type-coercions.html"><strong aria-hidden="true">7.7.</strong> Type coercions</a></li><li><a href="destructors.html"><strong aria-hidden="true">7.8.</strong> Destructors</a></li><li><a href="lifetime-elision.html"><strong aria-hidden="true">7.9.</strong> Lifetime elision</a></li></ol></li><li><a href="special-types-and-traits.html"><strong aria-hidden="true">8.</strong> Special types and traits</a></li><li><a href="memory-model.html"><strong aria-hidden="true">9.</strong> Memory model</a></li><li><ol class="section"><li><a href="memory-allocation-and-lifetime.html"><strong aria-hidden="true">9.1.</strong> Memory allocation and lifetime</a></li><li><a href="memory-ownership.html"><strong aria-hidden="true">9.2.</strong> Memory ownership</a></li><li><a href="variables.html"><strong aria-hidden="true">9.3.</strong> Variables</a></li></ol></li><li><a href="linkage.html"><strong aria-hidden="true">10.</strong> Linkage</a></li><li><a href="unsafety.html"><strong aria-hidden="true">11.</strong> Unsafety</a></li><li><ol class="section"><li><a href="unsafe-functions.html"><strong aria-hidden="true">11.1.</strong> Unsafe functions</a></li><li><a href="unsafe-blocks.html"><strong aria-hidden="true">11.2.</strong> Unsafe blocks</a></li><li><a href="behavior-considered-undefined.html"><strong aria-hidden="true">11.3.</strong> Behavior considered undefined</a></li><li><a href="behavior-not-considered-unsafe.html"><strong aria-hidden="true">11.4.</strong> Behavior not considered unsafe</a></li></ol></li><li><a href="influences.html">Appendix: Influences</a></li><li class="affix"><a href="undocumented.html">Appendix: As-yet-undocumented Features</a></li><li class="affix"><a href="glossary.html">Appendix: Glossary</a></li></ol>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<header><p class="warning">
For now, this reference is a best-effort document. We strive for validity
and completeness, but are not yet there. In the future, the docs and lang
teams will work together to figure out how best to do this. Until then, this
is a best-effort attempt. If you find something wrong or missing, file an
<a href="https://github.com/rust-lang-nursery/reference/issues">issue</a> or
send in a pull request.
</p></header>
<div id="menu-bar" class="menu-bar">
<div id="menu-bar-sticky-container">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light <span class="default">(default)</span></button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">The Rust Reference</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<a class="header" href="attributes.html#attributes" id="attributes"><h1>Attributes</h1></a>
<blockquote>
<p><strong><sup>Syntax</sup></strong><br />
<em>Attribute</em> :<br />
<em>InnerAttribute</em> | <em>OuterAttribute</em></p>
<p><em>InnerAttribute</em> :<br />
<code>#![</code> MetaItem <code>]</code></p>
<p><em>OuterAttribute</em> :<br />
<code>#[</code> MetaItem <code>]</code></p>
<p><em>MetaItem</em> :<br />
IDENTIFIER<br />
| IDENTIFIER <code>=</code> LITERAL<br />
| IDENTIFIER <code>(</code> LITERAL <code>)</code><br />
| IDENTIFIER <code>(</code> <em>MetaSeq</em> <code>)</code></p>
<p><em>MetaSeq</em> :<br />
EMPTY<br />
| <em>MetaItem</em><br />
| <em>MetaItem</em> <code>,</code> <em>MetaSeq</em></p>
</blockquote>
<p>Any <a href="items.html">item declaration</a> or <a href="items/generics.html">generic lifetime or type parameter</a> may
have an attribute applied to it. Attributes are modeled on Attributes in
<a href="https://www.ecma-international.org/publications/standards/Ecma-335.htm">ECMA-335</a>, with the syntax coming from <a href="https://www.ecma-international.org/publications/standards/Ecma-334.htm">ECMA-334</a> (C#). An <em>attribute</em> is a
general, free-form metadatum that is interpreted according to name, convention,
and language and compiler version. Attributes may appear as any of:</p>
<ul>
<li>A single identifier, the attribute name</li>
<li>An identifier followed by the equals sign '=' and a literal, providing a
key/value pair</li>
<li>An identifier followed by a parenthesized literal, providing a
key/value pair</li>
<li>An identifier followed by a parenthesized list of sub-attribute arguments</li>
</ul>
<p><em>Inner attributes</em>, written with a bang ("!") after the hash ("#"), apply to the
item that the attribute is declared within. <em>Outer attributes</em>, written without
the bang after the hash, apply to the item or generic parameter that follow the
attribute.</p>
<p>An example of attributes:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
// General metadata applied to the enclosing module or crate.
#![crate_type = "lib"]
// A function marked as a unit test
#[test]
fn test_foo() {
/* ... */
}
// A conditionally-compiled module
#[cfg(target_os = "linux")]
mod bar {
/* ... */
}
// A lint attribute used to suppress a warning/error
#[allow(non_camel_case_types)]
type int8_t = i8;
#}</code></pre></pre>
<a class="header" href="attributes.html#crate-only-attributes" id="crate-only-attributes"><h2>Crate-only attributes</h2></a>
<ul>
<li><code>crate_name</code> - specify the crate's crate name.</li>
<li><code>crate_type</code> - see <a href="linkage.html">linkage</a>.</li>
<li><code>no_builtins</code> - disable optimizing certain code patterns to invocations of
library functions that are assumed to exist</li>
<li><code>no_main</code> - disable emitting the <code>main</code> symbol. Useful when some other
object being linked to defines <code>main</code>.</li>
<li><code>no_start</code> - disable linking to the <code>native</code> crate, which specifies the
"start" language item.</li>
<li><code>no_std</code> - disable linking to the <code>std</code> crate.</li>
<li><code>recursion_limit</code> - Sets the maximum depth for potentially
infinitely-recursive compile-time operations like
auto-dereference or macro expansion. The default is
<code>#![recursion_limit="64"]</code>.</li>
<li><code>windows_subsystem</code> - Indicates that when this crate is linked for a Windows
target it will configure the resulting binary's
<a href="https://msdn.microsoft.com/en-us/library/fcc1zstk.aspx">subsystem</a> via the linker. Valid values for this
attribute are <code>console</code> and <code>windows</code>, corresponding to
those two respective subsystems. More subsystems may be
allowed in the future, and this attribute is ignored on
non-Windows targets.</li>
</ul>
<a class="header" href="attributes.html#module-only-attributes" id="module-only-attributes"><h2>Module-only attributes</h2></a>
<ul>
<li><code>no_implicit_prelude</code> - disable injecting <code>use std::prelude::*</code> in this
module.</li>
<li><code>path</code> - specifies the file to load the module from. <code>#[path="foo.rs"] mod bar;</code> is equivalent to <code>mod bar { /* contents of foo.rs */ }</code>. The path is
taken relative to the directory that the current module is in.</li>
</ul>
<a class="header" href="attributes.html#function-only-attributes" id="function-only-attributes"><h2>Function-only attributes</h2></a>
<ul>
<li><code>test</code> - indicates that this function is a test function, to only be compiled
in case of <code>--test</code>.
<ul>
<li><code>ignore</code> - indicates that this test function is disabled.</li>
</ul>
</li>
<li><code>should_panic</code> - indicates that this test function should panic, inverting the
success condition.</li>
<li><code>cold</code> - The function is unlikely to be executed, so optimize it (and calls
to it) differently.</li>
</ul>
<a class="header" href="attributes.html#ffi-attributes" id="ffi-attributes"><h2>FFI attributes</h2></a>
<p>On an <code>extern</code> block, the following attributes are interpreted:</p>
<ul>
<li><code>link_args</code> - specify arguments to the linker, rather than just the library
name and type. This is feature gated and the exact behavior is
implementation-defined (due to variety of linker invocation syntax).</li>
<li><code>link</code> - indicate that a native library should be linked to for the
declarations in this block to be linked correctly. <code>link</code> supports an optional
<code>kind</code> key with three possible values: <code>dylib</code>, <code>static</code>, and <code>framework</code>. See
<a href="items/external-blocks.html">external blocks</a> for more about external blocks.
Two examples: <code>#[link(name = "readline")]</code> and
<code>#[link(name = "CoreFoundation", kind = "framework")]</code>.</li>
<li><code>linked_from</code> - indicates what native library this block of FFI items is
coming from. This attribute is of the form <code>#[linked_from = "foo"]</code> where
<code>foo</code> is the name of a library in either <code>#[link]</code> or a <code>-l</code> flag. This
attribute is currently required to export symbols from a Rust dynamic library
on Windows, and it is feature gated behind the <code>linked_from</code> feature.</li>
</ul>
<p>On declarations inside an <code>extern</code> block, the following attributes are
interpreted:</p>
<ul>
<li><code>link_name</code> - the name of the symbol that this function or static should be
imported as.</li>
<li><code>linkage</code> - on a static, this specifies the <a href="http://llvm.org/docs/LangRef.html#linkage-types">linkage
type</a>.</li>
</ul>
<p>See <a href="type-layout.html">type layout</a> for documentation on the <code>repr</code> attribute
which can be used to control type layout.</p>
<a class="header" href="attributes.html#macro-related-attributes" id="macro-related-attributes"><h2>Macro-related attributes</h2></a>
<ul>
<li>
<p><code>macro_use</code> on a <code>mod</code> — macros defined in this module will be visible in the
module's parent, after this module has been included.</p>
</li>
<li>
<p><code>macro_use</code> on an <code>extern crate</code> — load macros from this crate. An optional
list of names <code>#[macro_use(foo, bar)]</code> restricts the import to just those
macros named. The <code>extern crate</code> must appear at the crate root, not inside
<code>mod</code>, which ensures proper function of the <a href="../book/first-edition/macros.html#the-variable-crate"><code>$crate</code> macro
variable</a>.</p>
</li>
<li>
<p><code>macro_reexport</code> on an <code>extern crate</code> — re-export the named macros.</p>
</li>
<li>
<p><code>macro_export</code> - export a macro for cross-crate usage.</p>
</li>
<li>
<p><code>no_link</code> on an <code>extern crate</code> — even if we load this crate for macros, don't
link it into the output.</p>
</li>
</ul>
<p>See the <a href="../book/first-edition/macros.html#scoping-and-macro-importexport">macros section of the first edition of the
book</a> for more
information on macro scope.</p>
<a class="header" href="attributes.html#miscellaneous-attributes" id="miscellaneous-attributes"><h2>Miscellaneous attributes</h2></a>
<ul>
<li><code>export_name</code> - on statics and functions, this determines the name of the
exported symbol.</li>
<li><code>link_section</code> - on statics and functions, this specifies the section of the
object file that this item's contents will be placed into.</li>
<li><code>no_mangle</code> - on any item, do not apply the standard name mangling. Set the
symbol for this item to its identifier.</li>
</ul>
<a class="header" href="attributes.html#deprecation" id="deprecation"><h3>Deprecation</h3></a>
<p>The <code>deprecated</code> attribute marks an item as deprecated. It has two optional
fields, <code>since</code> and <code>note</code>.</p>
<ul>
<li><code>since</code> expects a version number, as in <code>#[deprecated(since = "1.4.1")]</code>
<ul>
<li><code>rustc</code> doesn't know anything about versions, but external tools like
<code>clippy</code> may check the validity of this field.</li>
</ul>
</li>
<li><code>note</code> is a free text field, allowing you to provide an explanation about
the deprecation and preferred alternatives.</li>
</ul>
<p>Only <a href="visibility-and-privacy.html">public items</a> can be given the
<code>#[deprecated]</code> attribute. <code>#[deprecated]</code> on a module is inherited by all
child items of that module.</p>
<p><code>rustc</code> will issue warnings on usage of <code>#[deprecated]</code> items. <code>rustdoc</code> will
show item deprecation, including the <code>since</code> version and <code>note</code>, if available.</p>
<p>Here's an example.</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
#[deprecated(since = "5.2", note = "foo was rarely used. Users should instead use bar")]
pub fn foo() {}
pub fn bar() {}
#}</code></pre></pre>
<p>The <a href="https://github.com/rust-lang/rfcs/blob/master/text/1270-deprecation.md">RFC</a> contains motivations and more details.</p>
<a class="header" href="attributes.html#documentation" id="documentation"><h3>Documentation</h3></a>
<p>The <code>doc</code> attribute is used to document items and fields. <a href="comments.html#doc-comments">Doc comments</a>
are transformed into <code>doc</code> attributes.</p>
<p>See <a href="../rustdoc/the-doc-attribute.html">The Rustdoc Book</a> for reference material on this attribute.</p>
<a class="header" href="attributes.html#conditional-compilation" id="conditional-compilation"><h3>Conditional compilation</h3></a>
<p>Sometimes one wants to have different compiler outputs from the same code,
depending on build target, such as targeted operating system, or to enable
release builds.</p>
<p>Configuration options are boolean (on or off) and are named either with a
single identifier (e.g. <code>foo</code>) or an identifier and a string (e.g. <code>foo = "bar"</code>;
the quotes are required and spaces around the <code>=</code> are unimportant). Note that
similarly-named options, such as <code>foo</code>, <code>foo="bar"</code> and <code>foo="baz"</code> may each be
set or unset independently.</p>
<p>Configuration options are either provided by the compiler or passed in on the
command line using <code>--cfg</code> (e.g. <code>rustc main.rs --cfg foo --cfg 'bar="baz"'</code>).
Rust code then checks for their presence using the <code>#[cfg(...)]</code> attribute:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
// The function is only included in the build when compiling for macOS
#[cfg(target_os = "macos")]
fn macos_only() {
// ...
}
// This function is only included when either foo or bar is defined
#[cfg(any(foo, bar))]
fn needs_foo_or_bar() {
// ...
}
// This function is only included when compiling for a unixish OS with a 32-bit
// architecture
#[cfg(all(unix, target_pointer_width = "32"))]
fn on_32bit_unix() {
// ...
}
// This function is only included when foo is not defined
#[cfg(not(foo))]
fn needs_not_foo() {
// ...
}
#}</code></pre></pre>
<p>This illustrates some conditional compilation can be achieved using the
<code>#[cfg(...)]</code> attribute. <code>any</code>, <code>all</code> and <code>not</code> can be used to assemble
arbitrarily complex configurations through nesting.</p>
<p>The following configurations must be defined by the implementation:</p>
<ul>
<li><code>target_arch = "..."</code> - Target CPU architecture, such as <code>"x86"</code>,
<code>"x86_64"</code> <code>"mips"</code>, <code>"powerpc"</code>, <code>"powerpc64"</code>, <code>"arm"</code>, or
<code>"aarch64"</code>. This value is closely related to the first element of
the platform target triple, though it is not identical.</li>
<li><code>target_os = "..."</code> - Operating system of the target, examples
include <code>"windows"</code>, <code>"macos"</code>, <code>"ios"</code>, <code>"linux"</code>, <code>"android"</code>,
<code>"freebsd"</code>, <code>"dragonfly"</code>, <code>"bitrig"</code> , <code>"openbsd"</code> or
<code>"netbsd"</code>. This value is closely related to the second and third
element of the platform target triple, though it is not identical.</li>
<li><code>target_family = "..."</code> - Operating system family of the target, e. g.
<code>"unix"</code> or <code>"windows"</code>. The value of this configuration option is defined
as a configuration itself, like <code>unix</code> or <code>windows</code>.</li>
<li><code>unix</code> - See <code>target_family</code>.</li>
<li><code>windows</code> - See <code>target_family</code>.</li>
<li><code>target_env = ".."</code> - Further disambiguates the target platform with
information about the ABI/libc. Presently this value is either
<code>"gnu"</code>, <code>"msvc"</code>, <code>"musl"</code>, or the empty string. For historical
reasons this value has only been defined as non-empty when needed
for disambiguation. Thus on many GNU platforms this value will be
empty. This value is closely related to the fourth element of the
platform target triple, though it is not identical. For example,
embedded ABIs such as <code>gnueabihf</code> will simply define <code>target_env</code> as
<code>"gnu"</code>.</li>
<li><code>target_endian = "..."</code> - Endianness of the target CPU, either <code>"little"</code> or
<code>"big"</code>.</li>
<li><code>target_pointer_width = "..."</code> - Target pointer width in bits. This is set
to <code>"32"</code> for targets with 32-bit pointers, and likewise set to <code>"64"</code> for
64-bit pointers.</li>
<li><code>target_has_atomic = "..."</code> - Set of integer sizes on which the target can perform
atomic operations. Values are <code>"8"</code>, <code>"16"</code>, <code>"32"</code>, <code>"64"</code> and <code>"ptr"</code>.</li>
<li><code>target_vendor = "..."</code> - Vendor of the target, for example <code>apple</code>, <code>pc</code>, or
simply <code>"unknown"</code>.</li>
<li><code>test</code> - Enabled when compiling the test harness (using the <code>--test</code> flag).</li>
<li><code>debug_assertions</code> - Enabled by default when compiling without optimizations.
This can be used to enable extra debugging code in development but not in
production. For example, it controls the behavior of the standard library's
<code>debug_assert!</code> macro.</li>
</ul>
<p>You can also set another attribute based on a <code>cfg</code> variable with <code>cfg_attr</code>:</p>
<pre><code class="language-rust ignore">#[cfg_attr(a, b)]
</code></pre>
<p>This is the same as <code>#[b]</code> if <code>a</code> is set by <code>cfg</code>, and nothing otherwise.</p>
<p>Lastly, configuration options can be used in expressions by invoking the <code>cfg!</code>
macro: <code>cfg!(a)</code> evaluates to <code>true</code> if <code>a</code> is set, and <code>false</code> otherwise.</p>
<a class="header" href="attributes.html#lint-check-attributes" id="lint-check-attributes"><h3>Lint check attributes</h3></a>
<p>A lint check names a potentially undesirable coding pattern, such as
unreachable code or omitted documentation, for the static entity to which the
attribute applies.</p>
<p>For any lint check <code>C</code>:</p>
<ul>
<li><code>allow(C)</code> overrides the check for <code>C</code> so that violations will go
unreported,</li>
<li><code>deny(C)</code> signals an error after encountering a violation of <code>C</code>,</li>
<li><code>forbid(C)</code> is the same as <code>deny(C)</code>, but also forbids changing the lint
level afterwards,</li>
<li><code>warn(C)</code> warns about violations of <code>C</code> but continues compilation.</li>
</ul>
<p>The lint checks supported by the compiler can be found via <code>rustc -W help</code>,
along with their default settings. <a href="../unstable-book/language-features/plugin.html#lint-plugins">Compiler
plugins</a> can provide additional lint checks.</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
pub mod m1 {
// Missing documentation is ignored here
#[allow(missing_docs)]
pub fn undocumented_one() -> i32 { 1 }
// Missing documentation signals a warning here
#[warn(missing_docs)]
pub fn undocumented_too() -> i32 { 2 }
// Missing documentation signals an error here
#[deny(missing_docs)]
pub fn undocumented_end() -> i32 { 3 }
}
#}</code></pre></pre>
<p>This example shows how one can use <code>allow</code> and <code>warn</code> to toggle a particular
check on and off:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
#[warn(missing_docs)]
pub mod m2{
#[allow(missing_docs)]
pub mod nested {
// Missing documentation is ignored here
pub fn undocumented_one() -> i32 { 1 }
// Missing documentation signals a warning here,
// despite the allow above.
#[warn(missing_docs)]
pub fn undocumented_two() -> i32 { 2 }
}
// Missing documentation signals a warning here
pub fn undocumented_too() -> i32 { 3 }
}
#}</code></pre></pre>
<p>This example shows how one can use <code>forbid</code> to disallow uses of <code>allow</code> for
that lint check:</p>
<pre><pre class="playpen"><code class="language-rust compile_fail">
# #![allow(unused_variables)]
#fn main() {
#[forbid(missing_docs)]
pub mod m3 {
// Attempting to toggle warning signals an error here
#[allow(missing_docs)]
/// Returns 2.
pub fn undocumented_too() -> i32 { 2 }
}
#}</code></pre></pre>
<a class="header" href="attributes.html#must_use-attribute" id="must_use-attribute"><h4><code>must_use</code> Attribute</h4></a>
<p>The <code>must_use</code> attribute can be used on user-defined composite types
(<a href="items/structs.html"><code>struct</code>s</a>, <a href="items/enumerations.html"><code>enum</code>s</a>, and <a href="items/unions.html"><code>union</code>s</a>) and <a href="items/functions.html">functions</a>.</p>
<p>When used on user-defined composite types, if the <a href="expressions.html">expression</a> of an
<a href="statements.html#expression-statements">expression statement</a> has that type, then the <code>unused_must_use</code> lint is
violated.</p>
<pre><pre class="playpen"><code class="language-rust">#[must_use]
struct MustUse {
// some fields
}
# impl MustUse {
# fn new() -> MustUse { MustUse {} }
# }
#
fn main() {
// Violates the `unused_must_use` lint.
MustUse::new();
}
</code></pre></pre>
<p>When used on a function, if the <a href="expressions.html">expression</a> of an
<a href="statements.html#expression-statements">expression statement</a> is a <a href="expressions/call-expr.html">call expression</a> to that function, then the
<code>unused_must_use</code> lint is violated. The exceptions to this is if the return type
of the function is <code>()</code>, <code>!</code>, or a <a href="items/enumerations.html#zero-variant-enums">zero-variant enum</a>, in which case the
attribute does nothing.</p>
<pre><pre class="playpen"><code class="language-rust">#[must_use]
fn five() -> i32 { 5i32 }
fn main() {
// Violates the unused_must_use lint.
five();
}
</code></pre></pre>
<p>When used on a function in a trait declaration, then the behavior also applies
when the call expression is a function from an implementation of the trait.</p>
<pre><pre class="playpen"><code class="language-rust">trait Trait {
#[must_use]
fn use_me(&self) -> i32;
}
impl Trait for i32 {
fn use_me(&self) -> i32 { 0i32 }
}
fn main() {
// Violates the `unused_must_use` lint.
5i32.use_me();
}
</code></pre></pre>
<p>When used on a function in an implementation, the attribute does nothing.</p>
<blockquote>
<p>Note: Trivial no-op expressions containing the value will not violate the
lint. Examples include wrapping the value in a type that does not implement
<a href="special-types-and-traits.html#drop"><code>Drop</code></a> and then not using that type and being the final expression of a
<a href="expressions/block-expr.html">block expression</a> that is not used.</p>
<pre><pre class="playpen"><code class="language-rust">#[must_use]
fn five() -> i32 { 5i32 }
fn main() {
// None of these violate the unused_must_use lint.
(five(),);
Some(five());
{ five() };
if true { five() } else { 0i32 };
match true {
_ => five()
};
}
</code></pre></pre>
</blockquote>
<blockquote>
<p>Note: It is idiomatic to use a <a href="statements.html#let-statements">let statement</a> with a pattern of <code>_</code>
when a must-used value is purposely discarded.</p>
<pre><pre class="playpen"><code class="language-rust">#[must_use]
fn five() -> i32 { 5i32 }
fn main() {
// Does not violate the unused_must_use lint.
let _ = five();
}
</code></pre></pre>
</blockquote>
<p>The <code>must_use</code> attribute may also include a message by using
<code>#[must_use = "message"]</code>. The message will be given alongside the warning.</p>
<a class="header" href="attributes.html#inline-attribute" id="inline-attribute"><h3>Inline attribute</h3></a>
<p>The inline attribute suggests that the compiler should place a copy of
the function or static in the caller, rather than generating code to
call the function or access the static where it is defined.</p>
<p>The compiler automatically inlines functions based on internal heuristics.
Incorrectly inlining functions can actually make the program slower, so it
should be used with care.</p>
<p><code>#[inline]</code> and <code>#[inline(always)]</code> always cause the function to be serialized
into the crate metadata to allow cross-crate inlining.</p>
<p>There are three different types of inline attributes:</p>
<ul>
<li><code>#[inline]</code> hints the compiler to perform an inline expansion.</li>
<li><code>#[inline(always)]</code> asks the compiler to always perform an inline expansion.</li>
<li><code>#[inline(never)]</code> asks the compiler to never perform an inline expansion.</li>
</ul>
<a class="header" href="attributes.html#derive" id="derive"><h3><code>derive</code></h3></a>
<p>The <code>derive</code> attribute allows certain traits to be automatically implemented
for data structures. For example, the following will create an <code>impl</code> for the
<code>PartialEq</code> and <code>Clone</code> traits for <code>Foo</code>, the type parameter <code>T</code> will be given
the <code>PartialEq</code> or <code>Clone</code> constraints for the appropriate <code>impl</code>:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
#[derive(PartialEq, Clone)]
struct Foo<T> {
a: i32,
b: T,
}
#}</code></pre></pre>
<p>The generated <code>impl</code> for <code>PartialEq</code> is equivalent to</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
# struct Foo<T> { a: i32, b: T }
impl<T: PartialEq> PartialEq for Foo<T> {
fn eq(&self, other: &Foo<T>) -> bool {
self.a == other.a && self.b == other.b
}
fn ne(&self, other: &Foo<T>) -> bool {
self.a != other.a || self.b != other.b
}
}
#}</code></pre></pre>
<p>You can implement <code>derive</code> for your own type through <a href="procedural-macros.html">procedural macros</a>.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="visibility-and-privacy.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="statements-and-expressions.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a href="visibility-and-privacy.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a href="statements-and-expressions.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script src="searchindex.js" type="text/javascript" charset="utf-8"></script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
</body>
</html>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
4e2dbb669434a7691662cb2f0ad38972
>
files
>
11068
