diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 6810f644b4b33..8ddce2edaee80 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -21,25 +21,30 @@ - [Conditional compilation](conditional-compilation.md) -- [Items and attributes](items-and-attributes.md) - - [Items](items.md) - - [Modules](items/modules.md) - - [Extern crates](items/extern-crates.md) - - [Use declarations](items/use-declarations.md) - - [Functions](items/functions.md) - - [Type aliases](items/type-aliases.md) - - [Structs](items/structs.md) - - [Enumerations](items/enumerations.md) - - [Unions](items/unions.md) - - [Constant items](items/constant-items.md) - - [Static items](items/static-items.md) - - [Traits](items/traits.md) - - [Implementations](items/implementations.md) - - [External blocks](items/external-blocks.md) +- [Items](items.md) + - [Modules](items/modules.md) + - [Extern crates](items/extern-crates.md) + - [Use declarations](items/use-declarations.md) + - [Functions](items/functions.md) + - [Type aliases](items/type-aliases.md) + - [Structs](items/structs.md) + - [Enumerations](items/enumerations.md) + - [Unions](items/unions.md) + - [Constant items](items/constant-items.md) + - [Static items](items/static-items.md) + - [Traits](items/traits.md) + - [Implementations](items/implementations.md) + - [External blocks](items/external-blocks.md) - [Type and lifetime parameters](items/generics.md) - [Associated Items](items/associated-items.md) - [Visibility and Privacy](visibility-and-privacy.md) - - [Attributes](attributes.md) + +- [Attributes](attributes.md) + - [Testing](attributes/testing.md) + - [Derive](attributes/derive.md) + - [Diagnostics](attributes/diagnostics.md) + - [Code generation](attributes/codegen.md) + - [Limits](attributes/limits.md) - [Statements and expressions](statements-and-expressions.md) - [Statements](statements.md) diff --git a/src/abi.md b/src/abi.md index 451bdda1b9e15..642ac42bcdf90 100644 --- a/src/abi.md +++ b/src/abi.md @@ -56,7 +56,40 @@ $ nm -C foo.o 0000000000000000 T foo::quux ``` +## The `no_mangle` attribute + +The *`no_mangle` attribute* may be used on any [item] to disable standard +symbol name mangling. The symbol for the item will be the identifier of the +item's name. + +## The `link_section` attribute + +The *`link_section` attribute* specifies the section of the object file that a +[function] or [static]'s content will be placed into. It uses the +[_MetaNameValueStr_] syntax to specify the section name. + +```rust,ignore +#[no_mangle] +#[link_section = ".example_section"] +pub static VAR1: u32 = 1; +``` + +## The `export_name` attribute + +The *`export_name` attribute* specifies the name of the symbol that will be +exported on a [function] or [static]. It uses the [_MetaNameValueStr_] syntax +to specify the symbol name. + +```rust,ignore +#[export_name = "exported_symbol_name"] +pub fn name_in_rust() { } +``` + +[_MetaNameValueStr_]: attributes.html#meta-item-attribute-syntax [`static` items]: items/static-items.html [attribute]: attributes.html [extern functions]: items/functions.html#extern-functions [external blocks]: items/external-blocks.html +[function]: items/functions.html +[item]: items.html +[static]: items/static-items.html diff --git a/src/attributes-redirect.html b/src/attributes-redirect.html new file mode 100644 index 0000000000000..490db9c297d8f --- /dev/null +++ b/src/attributes-redirect.html @@ -0,0 +1,29 @@ + diff --git a/src/attributes.md b/src/attributes.md index 414cca42f15c5..31332081515bc 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -1,3 +1,4 @@ +{{#include attributes-redirect.html}} # Attributes > **Syntax**\ @@ -30,8 +31,8 @@ syntax](#meta-item-attribute-syntax) below for more details. Attributes can be classified into the following kinds: -* Built-in attributes -* [Macro attributes][attribute macro] +* [Built-in attributes] +* [Macro attributes][attribute macros] * [Derive macro helper attributes] * [Tool attributes](#tool-attributes) @@ -84,8 +85,8 @@ fn some_unused_variables() { ## Meta Item Attribute Syntax -A "meta item" is the syntax used for the _Attr_ rule by most built-in -attributes and the [`meta` macro fragment specifier]. It has the following +A "meta item" is the syntax used for the _Attr_ rule by most [built-in +attributes] and the [`meta` macro fragment specifier]. It has the following grammar: > **Syntax**\ @@ -104,456 +105,45 @@ grammar: Literal expressions in meta items must not include integer or float type suffixes. -Some examples of meta items are: -- `no_std` -- `doc = "example"` -- `cfg(any())` -- `deprecated(since = "1.2.0", note = "text")` -- `repr(align(32))` - -## Active and inert attributes - -An attribute is either active or inert. During attribute processing, *active -attributes* remove themselves from the thing they are on while *inert attributes* -stay on. - -The `cfg` and `cfg_attr` attributes are active. The `test` attribute is inert -when compiling for tests and active otherwise. Attribute macros are active. -All other attributes are inert. - ---- - -The rest of this page describes or links to descriptions of which attribute -names have meaning. - -## Crate-only attributes - -> **Note**: This section is in the process of being removed, with specific -> sections for each attribute. It is not the full list of crate-root attributes. - -- `crate_name` - specify the crate's crate name. -- `crate_type` - see [linkage](linkage.html). -- `no_builtins` - disable optimizing certain code patterns to invocations of - library functions that are assumed to exist -- `no_main` - disable emitting the `main` symbol. Useful when some other - object being linked to defines `main`. -- `no_start` - disable linking to the `native` crate, which specifies the - "start" language item. -- `recursion_limit` - Sets the maximum depth for potentially - infinitely-recursive compile-time operations like - auto-dereference or macro expansion. The default is - `#![recursion_limit="64"]`. -- `windows_subsystem` - Indicates that when this crate is linked for a Windows - target it will configure the resulting binary's - [subsystem] via the linker. Valid values for this - attribute are `console` and `windows`, corresponding to - those two respective subsystems. More subsystems may be - allowed in the future, and this attribute is ignored on - non-Windows targets. - -[subsystem]: https://msdn.microsoft.com/en-us/library/fcc1zstk.aspx - -## FFI attributes - -On an `extern` block, the following attributes are interpreted: - -- `link` - indicate that a native library should be linked to for the - declarations in this block to be linked correctly. `link` supports an optional - `kind` key with three possible values: `dylib`, `static`, and `framework`. See - [external blocks](items/external-blocks.html) for more about external blocks. - Two examples: `#[link(name = "readline")]` and - `#[link(name = "CoreFoundation", kind = "framework")]`. - -On declarations inside an `extern` block, the following attributes are -interpreted: - -- `link_name` - the name of the symbol that this function or static should be - imported as. - -See [type layout](type-layout.html) for documentation on the `repr` attribute -which can be used to control type layout. - -## Macro-related attributes - -- [`macro_use`] — Expands macro visibility, or imports macros from other - crates. - -- [`macro_export`] — Exports a `macro_rules` macro for cross-crate usage. - -- `no_link` on an `extern crate` — even if we load this crate for macros, don't - link it into the output. - -- `proc_macro` - Defines a [function-like macro]. - -- `proc_macro_derive` - Defines a [derive macro]. - -- `proc_macro_attribute` - Defines an [attribute macro]. - -## Miscellaneous attributes - -- `export_name` - on statics and functions, this determines the name of the - exported symbol. -- `global_allocator` - when applied to a static item implementing the - `GlobalAlloc` trait, sets the global allocator. -- `link_section` - on statics and functions, this specifies the section of the - object file that this item's contents will be placed into. -- `no_mangle` - on any item, do not apply the standard name mangling. Set the - symbol for this item to its identifier. -- [`used`] - on statics, this forces the compiler to keep the variable in the - output object file. -- [`panic_handler`] — sets the function to handle panics. - -### Deprecation - -The `deprecated` attribute marks an item as deprecated. It has two optional -fields, `since` and `note`. - -- `since` expects a version number, as in `#[deprecated(since = "1.4.1")]` - - `rustc` doesn't know anything about versions, but external tools like - `clippy` may check the validity of this field. -- `note` is a free text field, allowing you to provide an explanation about - the deprecation and preferred alternatives. - -Only [public items](visibility-and-privacy.html) can be given the -`#[deprecated]` attribute. `#[deprecated]` on a module is inherited by all -child items of that module. - -`rustc` will issue warnings on usage of `#[deprecated]` items. `rustdoc` will -show item deprecation, including the `since` version and `note`, if available. - -Here's an example. - -```rust -#[deprecated(since = "5.2", note = "foo was rarely used. Users should instead use bar")] -pub fn foo() {} - -pub fn bar() {} -``` - -The [RFC][1270-deprecation.md] contains motivations and more details. - -[1270-deprecation.md]: https://github.com/rust-lang/rfcs/blob/master/text/1270-deprecation.md - -### Documentation - -The `doc` attribute is used to document items and fields. [Doc comments] -are transformed into `doc` attributes. - -See [The Rustdoc Book] for reference material on this attribute. +Various built-in attributes use different subsets of the meta item syntax to +specify their inputs. The following grammar rules show some commonly used +forms: -### `path` - -The `path` attribute says where a [module]'s source file is. See [modules] for -more information. - -### Preludes - -The [prelude] behavior can be modified with attributes. The [`no_std`] attribute -changes the prelude to the core prelude while the [`no_implicit_prelude`] -prevents the prelude from being added to the module. - -### Testing - -The compiler comes with a default test framework. It works by attributing -functions with the `test` attribute. These functions are only compiled when -compiling with the test harness. Like [main], functions annotated with this -attribute must take no arguments, must not declare any -[trait or lifetime bounds], must not have any [where clauses], and its return -type must be one of the following: - -* `()` -* `Result<(), E> where E: Error` - - - -> Note: The implementation of which return types are allowed is determined by -> the unstable [`Termination`] trait. - - - -> Note: The test harness is ran by passing the `--test` argument to `rustc` or -> using `cargo test`. - -Tests that return `()` pass as long as they terminate and do not panic. Tests -that return a `Result` pass as long as they return `Ok(())`. Tests that do not -terminate neither pass nor fail. - -A function annotated with the `test` attribute can also be annotated with the -`ignore` attribute. The *`ignore` attribute* tells the test harness to not -execute that function as a test. It will still only be compiled when compiling -with the test harness. - -A function annotated with the `test` attribute that returns `()` can also be -annotated with the `should_panic` attribute. The *`should_panic` attribute* -makes the test only pass if it actually panics. - -### Conditional compilation - -The `cfg` and `cfg_attr` attributes control conditional compilation of [items] -and attributes. See the [conditional compilation] section for reference material -on these attributes. - -### Lint check attributes - -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. - -For any lint check `C`: - -* `allow(C)` overrides the check for `C` so that violations will go - unreported, -* `deny(C)` signals an error after encountering a violation of `C`, -* `forbid(C)` is the same as `deny(C)`, but also forbids changing the lint - level afterwards, -* `warn(C)` warns about violations of `C` but continues compilation. - -The lint checks supported by the compiler can be found via `rustc -W help`, -along with their default settings. [Compiler -plugins][unstable book plugin] can provide additional lint checks. - -```rust -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 } -} -``` - -This example shows how one can use `allow` and `warn` to toggle a particular -check on and off: - -```rust -#[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 } -} -``` - -This example shows how one can use `forbid` to disallow uses of `allow` for -that lint check: - -```rust,compile_fail -#[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 } -} -``` - -#### Tool lint attributes - -Tool lints let you use scoped lints, to `allow`, `warn`, `deny` or `forbid` lints of -certain tools. - -Currently `clippy` is the only available lint tool. - -They only get checked when the associated tool is active, so if you try to use an `allow` attribute for a nonexistent tool lint, the compiler will not warn about the nonexistent lint until you use the tool. - -Otherwise, they work just like regular lint attributes: - -```rust -// set the entire `pedantic` clippy lint group to warn -#![warn(clippy::pedantic)] -// silence warnings from the `filter_map` clippy lint -#![allow(clippy::filter_map)] - -fn main() { - // ... -} - -// silence the `cmp_nan` clippy lint just for this function -#[allow(clippy::cmp_nan)] -fn foo() { - // ... -} -``` - -#### `must_use` - -The `must_use` attribute can be used on user-defined composite types -([`struct`s][struct], [`enum`s][enum], and [`union`s][union]) and [functions]. - -When used on user-defined composite types, if the [expression] of an -[expression statement] has that type, then the `unused_must_use` lint is -violated. - -```rust -#[must_use] -struct MustUse { - // some fields -} - -# impl MustUse { -# fn new() -> MustUse { MustUse {} } -# } -# -fn main() { - // Violates the `unused_must_use` lint. - MustUse::new(); -} -``` - -When used on a function, if the [expression] of an -[expression statement] is a [call expression] to that function, then the -`unused_must_use` lint is violated. The exceptions to this is if the return type -of the function is `()`, `!`, or a [zero-variant enum], in which case the -attribute does nothing. - -```rust -#[must_use] -fn five() -> i32 { 5i32 } - -fn main() { - // Violates the unused_must_use lint. - five(); -} -``` - -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. - -```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(); -} -``` - -When used on a function in an implementation, the attribute does nothing. - -> 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 -> [`Drop`] and then not using that type and being the final expression of a -> [block expression] that is not used. +> **Syntax**\ +> _MetaWord_:\ +>    [IDENTIFIER] > -> ```rust -> #[must_use] -> fn five() -> i32 { 5i32 } +> _MetaNameValueStr_:\ +>    [IDENTIFIER] `=` ([STRING_LITERAL] | [RAW_STRING_LITERAL]) > -> fn main() { -> // None of these violate the unused_must_use lint. -> (five(),); -> Some(five()); -> { five() }; -> if true { five() } else { 0i32 }; -> match true { -> _ => five() -> }; -> } -> ``` - -> Note: It is idiomatic to use a [let statement] with a pattern of `_` -> when a must-used value is purposely discarded. +> _MetaListPaths_:\ +>    [IDENTIFIER] `(` ( [_SimplePath_] (`,` [_SimplePath_])* `,`? )? `)` > -> ```rust -> #[must_use] -> fn five() -> i32 { 5i32 } +> _MetaListIdents_:\ +>    [IDENTIFIER] `(` ( [IDENTIFIER] (`,` [IDENTIFIER])* `,`? )? `)` > -> fn main() { -> // Does not violate the unused_must_use lint. -> let _ = five(); -> } -> ``` - -The `must_use` attribute may also include a message by using -`#[must_use = "message"]`. The message will be given alongside the warning. - -### Optimization Hints - -The `cold` and `inline` attributes give suggestions to the compiler to compile -your code in a way that may be faster than what it would do without the hint. -The attributes are only suggestions, and the compiler may choose to ignore it. - -Both attributes can be used on closures, [functions] and function prototypes, -although they do not do anything on function prototypes. When applied to a -function in a [trait], they apply only to that function when used as a default -function for a trait implementation and not to all trait implementations. - -#### `inline` Attribute - -The *`inline` attribute* suggests to the compiler that it should place a copy of -the attributed function in the caller, rather than generating code to call the -function where it is defined. +> _MetaListNameValueStr_:\ +>    [IDENTIFIER] `(` ( _MetaNameValueStr_ (`,` _MetaNameValueStr_)* `,`? )? `)` -> ***Note***: The compiler automatically inlines functions based on internal -> heuristics. Incorrectly inlining functions can actually make the program -> slower, so this attribute should be used with care. - -There are three ways of using the inline attribute: - -* `#[inline]` hints the compiler to perform an inline expansion. -* `#[inline(always)]` asks the compiler to always perform an inline expansion. -* `#[inline(never)]` asks the compiler to never perform an inline expansion. - -#### `cold` Attribute - -The *`cold` attribute* suggests to the compiler that the attributed function or -closure is unlikely to be called. - -### `derive` - -The `derive` attribute allows certain traits to be automatically implemented -for data structures. For example, the following will create an `impl` for the -`PartialEq` and `Clone` traits for `Foo`, and the type parameter `T` will be given -the `PartialEq` or `Clone` constraints for the appropriate `impl`: +Some examples of meta items are: -```rust -#[derive(PartialEq, Clone)] -struct Foo { - a: i32, - b: T, -} -``` +Style | Example +------|-------- +_MetaWord_ | `no_std` +_MetaNameValueStr_ | `doc = "example"` +_MetaListPaths_ | `allow(unused, clippy::inline_always)` +_MetaListIdents_ | `macro_use(foo, bar)` +_MetaListNameValueStr_ | `link(name = "CoreFoundation", kind = "framework")` -The generated `impl` for `PartialEq` is equivalent to +## Active and inert attributes -```rust -# struct Foo { a: i32, b: T } -impl PartialEq for Foo { - fn eq(&self, other: &Foo) -> bool { - self.a == other.a && self.b == other.b - } - - fn ne(&self, other: &Foo) -> bool { - self.a != other.a || self.b != other.b - } -} -``` +An attribute is either active or inert. During attribute processing, *active +attributes* remove themselves from the thing they are on while *inert attributes* +stay on. -You can implement `derive` for your own traits through [procedural macros]. +The [`cfg`] and [`cfg_attr`] attributes are active. The [`test`] attribute is +inert when compiling for tests and active otherwise. [Attribute macros] are +active. All other attributes are inert. ## Tool attributes @@ -582,52 +172,133 @@ pub fn f() {} > Note: `rustc` currently recognizes the tools "clippy" and "rustfmt". +## Built-in attributes index + +The following is an index of all built-in attributes. + +- Conditional compilation + - [`cfg`] — Controls conditional compilation. + - [`cfg_attr`] — Conditionally includes attributes. +- Testing + - [`test`] — Marks a function as a test. + - [`ignore`] — Disables a test function. + - [`should_panic`] — Indicates a test should generate a panic. +- Derive + - [`derive`] — Automatic trait implementations. +- Macros + - [`macro_export`] — Exports a `macro_rules` macro for cross-crate usage. + - [`macro_use`] — Expands macro visibility, or imports macros from other + crates. + - [`proc_macro`] — Defines a function-like macro. + - [`proc_macro_derive`] — Defines a derive macro. + - [`proc_macro_attribute`] — Defines an attribute macro. +- Diagnostics + - [`allow`], [`warn`], [`deny`], [`forbid`] — Alters the default lint level. + - [`deprecated`] — Generates deprecation notices. + - [`must_use`] — Generates a lint for unused values. +- ABI, linking, symbols, and FFI + - [`link`] — Specifies a native library to link with an `extern` block. + - [`link_name`] — Specifies the name of the symbol for functions or statics + in an `extern` block. + - [`no_link`] — Prevents linking an extern crate. + - [`repr`] — Controls type layout. + - [`crate_type`] — Specifies the type of crate (library, executable, etc.). + - [`no_main`] — Disables emitting the `main` symbol. + - [`export_name`] — Specifies the exported symbol name for a function or + static. + - [`link_section`] — Specifies the section of an object file to use for a + function or static. + - [`no_mangle`] — Disables symbol name encoding. + - [`used`] — Forces the compiler to keep a static item in the output + object file. + - [`crate_name`] — Specifies the crate name. +- Code generation + - [`inline`] — Hint to inline code. + - [`cold`] — Hint that a function is unlikely to be called. + - [`no_builtins`] — Disables use of certain built-in functions. +- Documentation + - `doc` — Specifies documentation. See [The Rustdoc Book] for more + information. [Doc comments] are transformed into `doc` attributes. +- Preludes + - [`no_std`] — Removes std from the prelude. + - [`no_implicit_prelude`] — Disables prelude lookups within a module. +- Modules + - [`path`] — Specifies the filename for a module. +- Limits + - [`recursion_limit`] — Sets the maximum recursion limit for certain + compile-time operations. +- Runtime + - [`panic_handler`] — Sets the function to handle panics. + - [`global_allocator`] — Sets the global memory allocator. + - [`windows_subsystem`] — Specifies the windows subsystem to link with. +- Features + - `feature` — Used to enable unstable or experimental compiler features. See + [The Unstable Book] for features implemented in `rustc`. + +[Doc comments]: comments.html#doc-comments +[ECMA-334]: https://www.ecma-international.org/publications/standards/Ecma-334.htm +[ECMA-335]: https://www.ecma-international.org/publications/standards/Ecma-335.htm +[Expression Attributes]: expressions.html#expression-attributes +[IDENTIFIER]: identifiers.html +[RAW_STRING_LITERAL]: tokens.html#raw-string-literals +[STRING_LITERAL]: tokens.html#string-literals +[The Rustdoc Book]: ../rustdoc/the-doc-attribute.html +[The Unstable Book]: ../unstable-book/index.html [_DelimTokenTree_]: macros.html [_LiteralExpression_]: expressions/literal-expr.html [_SimplePath_]: paths.html#simple-paths +[`allow`]: attributes/diagnostics.html#lint-check-attributes +[`cfg_attr`]: conditional-compilation.html#the-cfg_attr-attribute +[`cfg`]: conditional-compilation.html#the-cfg-attribute +[`cold`]: attributes/codegen.html#the-cold-attribute +[`crate_name`]: crates-and-source-files.html#the-crate_name-attribute +[`crate_type`]: linkage.html +[`deny`]: attributes/diagnostics.html#lint-check-attributes +[`deprecated`]: attributes/diagnostics.html#the-deprecated-attribute +[`derive`]: attributes/derive.html +[`export_name`]: abi.html#the-export_name-attribute +[`forbid`]: attributes/diagnostics.html#lint-check-attributes +[`global_allocator`]: runtime.html#the-global_allocator-attribute +[`ignore`]: attributes/testing.html#the-ignore-attribute +[`inline`]: attributes/codegen.html#the-inline-attribute +[`link_name`]: items/external-blocks.html#the-link_name-attribute +[`link_section`]: abi.html#the-link_section-attribute +[`link`]: items/external-blocks.html#the-link-attribute +[`macro_export`]: macros-by-example.html#path-based-scope +[`macro_use`]: macros-by-example.html#the-macro_use-attribute +[`meta` macro fragment specifier]: macros-by-example.html +[`must_use`]: attributes/diagnostics.html#the-must_use-attribute +[`no_builtins`]: attributes/codegen.html#the-no_builtins-attribute [`no_implicit_prelude`]: items/modules.html#prelude-items +[`no_link`]: items/extern-crates.html#the-no_link-attribute +[`no_main`]: crates-and-source-files.html#the-no_main-attribute +[`no_mangle`]: abi.html#the-no_mangle-attribute [`no_std`]: crates-and-source-files.html#preludes-and-no_std -[Doc comments]: comments.html#doc-comments -[The Rustdoc Book]: ../rustdoc/the-doc-attribute.html -[module]: items/modules.html -[prelude]: crates-and-source-files.html#preludes-and-no_std -[procedural macros]: procedural-macros.html -[struct]: items/structs.html +[`panic_handler`]: runtime.html#the-panic_handler-attribute +[`path`]: items/modules.html#the-path-attribute +[`proc_macro_attribute`]: procedural-macros.html#attribute-macros +[`proc_macro_derive`]: procedural-macros.html#derive-macros +[`proc_macro`]: procedural-macros.html#function-like-procedural-macros +[`recursion_limit`]: attributes/limits.html#the-recursion_limit-attribute +[`repr`]: type-layout.html#representations +[`should_panic`]: attributes/testing.html#the-should_panic-attribute +[`test`]: attributes/testing.html#the-test-attribute +[`used`]: abi.html#the-used-attribute +[`warn`]: attributes/diagnostics.html#lint-check-attributes +[`windows_subsystem`]: runtime.html#the-windows_subsystem-attribute +[attribute macros]: procedural-macros.html#attribute-macros +[block expressions]: expressions/block-expr.html +[built-in attributes]: #built-in-attributes-index +[derive macro helper attributes]: procedural-macros.html#derive-macro-helper-attributes [enum]: items/enumerations.html -[union]: items/unions.html -[functions]: items/functions.html -[expression]: expressions.html [expression statement]: statements.html#expression-statements -[call expression]: expressions/call-expr.html -[block expression]: expressions/block-expr.html -[block expressions]: expressions/block-expr.html -[`Drop`]: special-types-and-traits.html#drop -[let statement]: statements.html#let-statements -[unstable book plugin]: ../unstable-book/language-features/plugin.html#lint-plugins -[zero-variant enum]: items/enumerations.html#zero-variant-enums -[ECMA-334]: https://www.ecma-international.org/publications/standards/Ecma-334.htm -[ECMA-335]: https://www.ecma-international.org/publications/standards/Ecma-335.htm -[item declarations]: items.html +[external blocks]: items/external-blocks.html +[functions]: items/functions.html [generics]: items/generics.html [implementations]: items/implementations.html +[item declarations]: items.html +[match expressions]: expressions/match-expr.html [modules]: items/modules.html [statements]: statements.html -[match expressions]: expressions/match-expr.html -[external blocks]: items/external-blocks.html -[items]: items.html -[attribute macro]: procedural-macros.html#attribute-macros -[derive macro helper attributes]: procedural-macros.html#derive-macro-helper-attributes -[function-like macro]: procedural-macros.html#function-like-procedural-macros -[conditional compilation]: conditional-compilation.html -[derive macro]: procedural-macros.html#derive-macros -[trait]: items/traits.html -[main]: crates-and-source-files.html -[`Termination`]: ../std/process/trait.Termination.html -[where clause]: items/where-clauses.html -[trait or lifetime bounds]: trait-bounds.html -[Expression Attributes]: expressions.html#expression-attributes -[`meta` macro fragment specifier]: macros-by-example.html -[`used`]: abi.html#the-used-attribute -[`panic_handler`]: runtime.html#the-panic_handler-attribute -[`macro_use`]: macros-by-example.html#the-macro_use-attribute -[`macro_export`]: macros-by-example.html#path-based-scope +[struct]: items/structs.html +[union]: items/unions.html diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md new file mode 100644 index 0000000000000..384cbc013cf61 --- /dev/null +++ b/src/attributes/codegen.md @@ -0,0 +1,48 @@ +# Code generation attributes + +The following [attributes] are used for controlling code generation. + +## Optimization hints + +The `cold` and `inline` [attributes] give suggestions to generate code in a +way that may be faster than what it would do without the hint. The attributes +are only hints, and may be ignored. + +Both attributes can be used on [functions]. When applied to a function in a +[trait], they apply only to that function when used as a default function for +a trait implementation and not to all trait implementations. The attributes +have no effect on a trait function without a body. + +### The `inline` attribute + +The *`inline` [attribute]* suggests that a copy of the attributed function +should be placed in the caller, rather than generating code to call the +function where it is defined. + +> ***Note***: The `rustc` compiler automatically inlines functions based on +> internal heuristics. Incorrectly inlining functions can make the program +> slower, so this attribute should be used with care. + +There are three ways to use the inline attribute: + +* `#[inline]` suggests performing an inline expansion. +* `#[inline(always)]` suggests that an inline expansion should always be + performed. +* `#[inline(never)]` suggests that an inline expansion should never be + performed. + +### The `cold` attribute + +The *`cold` [attribute]* suggests that the attributed function is unlikely to +be called. + +## The `no_builtins` attribute + +The *`no_builtins` [attribute]* may be applied at the crate level to disable +optimizing certain code patterns to invocations of library functions that are +assumed to exist. + +[attribute]: attributes.html +[attributes]: attributes.html +[functions]: items/functions.html +[trait]: items/traits.html diff --git a/src/attributes/derive.md b/src/attributes/derive.md new file mode 100644 index 0000000000000..ba0496a609427 --- /dev/null +++ b/src/attributes/derive.md @@ -0,0 +1,42 @@ +# Derive + +The *`derive` attribute* allows new [items] to be automatically generated for +data structures. It uses the [_MetaListPaths_] syntax to specify a list of +traits to implement or paths to [derive macros] to process. + +For example, the following will create an [`impl` item] for the +[`PartialEq`] and [`Clone`] traits for `Foo`, and the type parameter `T` will be +given the `PartialEq` or `Clone` constraints for the appropriate `impl`: + +```rust +#[derive(PartialEq, Clone)] +struct Foo { + a: i32, + b: T, +} +``` + +The generated `impl` for `PartialEq` is equivalent to + +```rust +# struct Foo { a: i32, b: T } +impl PartialEq for Foo { + fn eq(&self, other: &Foo) -> bool { + self.a == other.a && self.b == other.b + } + + fn ne(&self, other: &Foo) -> bool { + self.a != other.a || self.b != other.b + } +} +``` + +You can implement `derive` for your own traits through [procedural macros]. + +[_MetaListPaths_]: attributes.html#meta-item-attribute-syntax +[`Clone`]: ../std/clone/trait.Clone.html +[`PartialEq`]: ../std/cmp/trait.PartialEq.html +[`impl` item]: items/implementations.html +[items]: items.html +[derive macros]: procedural-macros.html#derive-macros +[procedural macros]: procedural-macros.html#derive-macros diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md new file mode 100644 index 0000000000000..1e6f3a09c2a5a --- /dev/null +++ b/src/attributes/diagnostics.md @@ -0,0 +1,281 @@ +# Diagnostic attributes + +The following [attributes] are used for controlling or generating diagnostic +messages during compilation. + +## Lint check attributes + +A lint check names a potentially undesirable coding pattern, such as +unreachable code or omitted documentation. The lint attributes `allow`, +`warn`, `deny`, and `forbid` use the [_MetaListPaths_] syntax to specify a +list of lint names to change the lint level for the entity to which the +attribute applies. + +For any lint check `C`: + +* `allow(C)` overrides the check for `C` so that violations will go + unreported, +* `warn(C)` warns about violations of `C` but continues compilation. +* `deny(C)` signals an error after encountering a violation of `C`, +* `forbid(C)` is the same as `deny(C)`, but also forbids changing the lint + level afterwards, + +> Note: The lint checks supported by `rustc` can be found via `rustc -W help`, +> along with their default settings and are documented in the [rustc book]. + +```rust +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 } +} +``` + +This example shows how one can use `allow` and `warn` to toggle a particular +check on and off: + +```rust +#[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 } +} +``` + +This example shows how one can use `forbid` to disallow uses of `allow` for +that lint check: + +```rust,compile_fail +#[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 } +} +``` + +### Tool lint attributes + +Tool lints allows using scoped lints, to `allow`, `warn`, `deny` or `forbid` +lints of certain tools. + +Currently `clippy` is the only available lint tool. + +Tool lints only get checked when the associated tool is active. If a lint +attribute, such as `allow`, references a nonexistent tool lint, the compiler +will not warn about the nonexistent lint until you use the tool. + +Otherwise, they work just like regular lint attributes: + +```rust +// set the entire `pedantic` clippy lint group to warn +#![warn(clippy::pedantic)] +// silence warnings from the `filter_map` clippy lint +#![allow(clippy::filter_map)] + +fn main() { + // ... +} + +// silence the `cmp_nan` clippy lint just for this function +#[allow(clippy::cmp_nan)] +fn foo() { + // ... +} +``` + +## The `deprecated` attribute + +The *`deprecated` attribute* marks an item as deprecated. `rustc` will issue +warnings on usage of `#[deprecated]` items. `rustdoc` will show item +deprecation, including the `since` version and `note`, if available. + +The `deprecated` attribute has several forms: + +- `deprecated` — Issues a generic message. +- `deprecated = "message"` — Includes the given string in the deprecation + message. +- [_MetaListNameValueStr_] syntax with two optional fields: + - `since` — Specifies a version number when the item was deprecated. `rustc` + does not currently interpret the string, but external tools like [Clippy] + may check the validity of the value. + - `note` — Specifies a string that should be included in the deprecation + message. This is typically used to provide an explanation about the + deprecation and preferred alternatives. + +The `deprecated` attribute may be applied to any [item], [trait item], [enum +variant], [struct field], or [external block item]. It cannot be applied to [trait +implementation items]. When applied to an item containing other items, such as +a [module] or [implementation], all child items inherit the deprecation attribute. + + +Here is an example: + +```rust +#[deprecated(since = "5.2", note = "foo was rarely used. Users should instead use bar")] +pub fn foo() {} + +pub fn bar() {} +``` + +The [RFC][1270-deprecation.md] contains motivations and more details. + +[1270-deprecation.md]: https://github.com/rust-lang/rfcs/blob/master/text/1270-deprecation.md + +## The `must_use` attribute + +The *`must_use` attribute* is used to issue a diagnostic warning when a value +is not "used". It can be applied to user-defined composite types +([`struct`s][struct], [`enum`s][enum], and [`union`s][union]), [functions], +and [traits]. + +The `must_use` attribute may include a message by using the +[_MetaNameValueStr_] syntax such as `#[must_use = "example message"]`. The +message will be given alongside the warning. + +When used on user-defined composite types, if the [expression] of an +[expression statement] has that type, then the `unused_must_use` lint is +violated. + +```rust +#[must_use] +struct MustUse { + // some fields +} + +# impl MustUse { +# fn new() -> MustUse { MustUse {} } +# } +# +// Violates the `unused_must_use` lint. +MustUse::new(); +``` + +When used on a function, if the [expression] of an [expression statement] is a +[call expression] to that function, then the `unused_must_use` lint is +violated. + +```rust +#[must_use] +fn five() -> i32 { 5i32 } + +// Violates the unused_must_use lint. +five(); +``` + +When used on a [trait declaration], a [call expression] of an [expression +statement] to a function that returns an [impl trait] of that trait violates +the `unsued_must_use` lint. + +```rust +#[must_use] +trait Critical {} +impl Critical for i32 {} + +fn get_critical() -> impl Critical { + 4i32 +} + +// Violates the `unused_must_use` lint. +get_critical(); +``` + +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. + +```rust +trait Trait { + #[must_use] + fn use_me(&self) -> i32; +} + +impl Trait for i32 { + fn use_me(&self) -> i32 { 0i32 } +} + +// Violates the `unused_must_use` lint. +5i32.use_me(); +``` + +When used on a function in a trait implementation, the attribute does nothing. + +> 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 +> [`Drop`] and then not using that type and being the final expression of a +> [block expression] that is not used. +> +> ```rust +> #[must_use] +> fn five() -> i32 { 5i32 } +> +> // None of these violate the unused_must_use lint. +> (five(),); +> Some(five()); +> { five() }; +> if true { five() } else { 0i32 }; +> match true { +> _ => five() +> }; +> ``` + +> Note: It is idiomatic to use a [let statement] with a pattern of `_` +> when a must-used value is purposely discarded. +> +> ```rust +> #[must_use] +> fn five() -> i32 { 5i32 } +> +> // Does not violate the unused_must_use lint. +> let _ = five(); +> ``` + +[Clippy]: https://github.com/rust-lang/rust-clippy +[_MetaListNameValueStr_]: attributes.html#meta-item-attribute-syntax +[_MetaListPaths_]: attributes.html#meta-item-attribute-syntax +[_MetaNameValueStr_]: attributes.html#meta-item-attribute-syntax +[`Drop`]: special-types-and-traits.html#drop +[attributes]: attributes.html +[block expression]: expressions/block-expr.html +[call expression]: expressions/call-expr.html +[enum variant]: items/enumerations.html +[enum]: items/enumerations.html +[expression statement]: statements.html#expression-statements +[expression]: expressions.html +[external block item]: items/external-blocks.html +[functions]: items/functions.html +[impl trait]: types/impl-trait.html +[implementation]: items/implementations.html +[item]: items.html +[let statement]: statements.html#let-statements +[module]: items/modules.html +[rustc book]: ../rustc/lints/index.html +[struct field]: items/structs.html +[struct]: items/structs.html +[trait declaration]: items/traits.html +[trait implementation items]: items/implementations.html#trait-implementations +[trait item]: items/traits.html +[traits]: items/traits.html +[union]: items/unions.html diff --git a/src/attributes/limits.md b/src/attributes/limits.md new file mode 100644 index 0000000000000..bc11e42d7c32e --- /dev/null +++ b/src/attributes/limits.md @@ -0,0 +1,14 @@ +# Limits + +The following [attributes] affect compile-time limits. + +## The `recursion_limit` attribute + +The *`recursion_limit` attribute* may be applied at the crate level to set the +maximum depth for potentially infinitely-recursive compile-time operations +like auto-dereference or macro expansion. It uses the [_MetaNameValueStr_] +syntax to specify the recursion depth. The default is +`#![recursion_limit="64"]`. + +[attributes]: attributes.html +[_MetaNameValueStr_]: attributes.html#meta-item-attribute-syntax diff --git a/src/attributes/testing.md b/src/attributes/testing.md new file mode 100644 index 0000000000000..066943377bae7 --- /dev/null +++ b/src/attributes/testing.md @@ -0,0 +1,91 @@ +# Testing attributes + +The following [attributes] are used for specifying functions for performing +tests. Compiling a crate in "test" mode enables building the test functions +along with a test harness for executing the tests. Enabling the test mode also +enables the [`test` conditional compilation option]. + +## The `test` attribute + +The *`test` attribute* marks a function to be executed as a test. These +functions are only compiled when in test mode. Test functions must be free, +monomorphic functions that take no arguments, and the return type must be one +of the following: + +* `()` +* `Result<(), E> where E: Error` + + + +> Note: The implementation of which return types are allowed is determined by +> the unstable [`Termination`] trait. + + + +> Note: The test mode is enabled by passing the `--test` argument to `rustc` +> or using `cargo test`. + +Tests that return `()` pass as long as they terminate and do not panic. Tests +that return a `Result<(), E>` pass as long as they return `Ok(())`. Tests that +do not terminate neither pass nor fail. + +```rust +# use std::io; +# fn setup_the_thing() -> io::Result { Ok(1) } +# fn do_the_thing(s: &i32) -> io::Result<()> { Ok(()) } +#[test] +fn test_the_thing() -> io::Result<()> { + let state = setup_the_thing()?; // expected to succeed + do_the_thing(&state)?; // expected to succeed + Ok(()) +} +``` + +## The `ignore` attribute + +A function annotated with the `test` attribute can also be annotated with the +`ignore` attribute. The *`ignore` attribute* tells the test harness to not +execute that function as a test. It will still be compiled when in test mode. + +The `ignore` attribute may optionally be written with the [_MetaNameValueStr_] +syntax to specify a reason why the test is ignored. + +```rust +#[test] +#[ignore = "not yet implemented"] +fn mytest() { + // … +} +``` + +> **Note**: The `rustc` test harness supports the `--include-ignored` flag to +> force ignored tests to be run. + +## The `should_panic` attribute + +A function annotated with the `test` attribute that returns `()` can also be +annotated with the `should_panic` attribute. The *`should_panic` attribute* +makes the test only pass if it actually panics. + +The `should_panic` attribute may optionally take an input string that must +appear within the panic message. If the string is not found in the message, +then the test will fail. The string may be passed using the +[_MetaNameValueStr_] syntax or the [_MetaListNameValueStr_] syntax with an +`expected` field. + +```rust +#[test] +#[should_panic(expected = "values don't match")] +fn mytest() { + assert_eq!(1, 2, "values don't match"); +} +``` + +[_MetaListNameValueStr_]: attributes.html#meta-item-attribute-syntax +[_MetaNameValueStr_]: attributes.html#meta-item-attribute-syntax +[`Termination`]: ../std/process/trait.Termination.html +[`test` conditional compilation option]: conditional-compilation.html#test +[attributes]: attributes.html +[trait or lifetime bounds]: trait-bounds.html +[where clauses]: items/generics.html#where-clauses diff --git a/src/comments.md b/src/comments.md index d8be2fef4166a..59442c67eee64 100644 --- a/src/comments.md +++ b/src/comments.md @@ -43,7 +43,7 @@ Non-doc comments are interpreted as a form of whitespace. Line doc comments beginning with exactly _three_ slashes (`///`), and block doc comments (`/** ... */`), both inner doc comments, are interpreted as a -special syntax for `doc` [attributes]. That is, they are equivalent to writing +special syntax for [`doc` attributes]. That is, they are equivalent to writing `#[doc="..."]` around the body of the comment, i.e., `/// Foo` turns into `#[doc="Foo"]` and `/** Bar */` turns into `#[doc="Bar"]`. @@ -122,4 +122,4 @@ pub mod outer_module { } ``` -[attributes]: attributes.html +[`doc` attributes]: ../rustdoc/the-doc-attribute.html diff --git a/src/conditional-compilation.md b/src/conditional-compilation.md index 760f1d8629485..5c3d6fd4f0c09 100644 --- a/src/conditional-compilation.md +++ b/src/conditional-compilation.md @@ -167,7 +167,7 @@ Example values: ### `test` Enabled when compiling the test harness. Done with `rustc` by using the -[`--test`] flag. +[`--test`] flag. See [Testing] for more on testing support. ### `debug_assertions` @@ -297,6 +297,7 @@ println!("I'm running on a {} machine!", machine_kind); [IDENTIFIER]: identifiers.html [RAW_STRING_LITERAL]: tokens.html#raw-string-literals [STRING_LITERAL]: tokens.html#string-literals +[Testing]: attributes/testing.html [_Attr_]: attributes.html [`--cfg`]: ../rustc/command-line-arguments.html#a--cfg-configure-the-compilation-environment [`--test`]: ../rustc/command-line-arguments.html#a--test-build-a-test-harness @@ -307,5 +308,3 @@ println!("I'm running on a {} machine!", machine_kind); [attribute]: attributes.html [attributes]: attributes.html [crate type]: linkage.html -[expressions]: expressions.html -[items]: items.html diff --git a/src/crates-and-source-files.md b/src/crates-and-source-files.md index 89599d68bc2e6..ccb94a2f3dd7c 100644 --- a/src/crates-and-source-files.md +++ b/src/crates-and-source-files.md @@ -123,7 +123,25 @@ type must be one of the following: > the unstable [`Termination`] trait. + onwards, also update it in the testing.md file --> + +### The `no_main` attribute + +The *`no_main` [attribute]* may be applied at the crate level to disable +emitting the `main` symbol for an executable binary. This is useful when some +other object being linked to defines `main`. + +## The `crate_name` attribute + +The *`crate_name` [attribute]* may be applied at the crate level to specify the +name of the crate with the [_MetaNameValueStr_] syntax. + +```rust,ignore +#![crate_name = "mycrate"] +``` + +The crate name must not be empty, and must only contain [Unicode alphanumeric] +or `-` (U+002D) characters. [^phase-distinction]: This distinction would also exist in an interpreter. Static checks like syntactic analysis, type checking, and lints should @@ -133,8 +151,10 @@ type must be one of the following: ECMA-335 CLI model, a *library* in the SML/NJ Compilation Manager, a *unit* in the Owens and Flatt module system, or a *configuration* in Mesa. +[Unicode alphanumeric]: ../std/primitive.char.html#method.is_alphanumeric [_InnerAttribute_]: attributes.html [_Item_]: items.html +[_MetaNameValueStr_]: attributes.html#meta-item-attribute-syntax [_shebang_]: https://en.wikipedia.org/wiki/Shebang_(Unix) [_utf8 byte order mark_]: https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8 [`Termination`]: ../std/process/trait.Termination.html diff --git a/src/expressions/block-expr.md b/src/expressions/block-expr.md index d1cb9affe3d82..aa1b124c07b7e 100644 --- a/src/expressions/block-expr.md +++ b/src/expressions/block-expr.md @@ -148,7 +148,7 @@ fn is_unix_platform() -> bool { [statement]: statements.html [statements]: statements.html [struct]: expressions/struct-expr.html -[the lint check attributes]: attributes.html#lint-check-attributes +[the lint check attributes]: attributes/diagnostics.html#lint-check-attributes [tuple expressions]: expressions/tuple-expr.html [unsafe operations]: unsafety.html [value expressions]: expressions.html#place-expressions-and-value-expressions diff --git a/src/expressions/match-expr.md b/src/expressions/match-expr.md index d032a3fcc49d9..a5ccf68299efe 100644 --- a/src/expressions/match-expr.md +++ b/src/expressions/match-expr.md @@ -128,7 +128,7 @@ let message = match maybe_digit { ## Attributes on match arms Outer attributes are allowed on match arms. The only attributes that have -meaning on match arms are [`cfg`], `cold`, and the [lint check attributes]. +meaning on match arms are [`cfg`], [`cold`], and the [lint check attributes]. [Inner attributes] are allowed directly after the opening brace of the match expression in the same expression contexts as [attributes on block @@ -141,7 +141,8 @@ expressions]. [_InnerAttribute_]: attributes.html [_OuterAttribute_]: attributes.html [`cfg`]: conditional-compilation.html -[lint check attributes]: attributes.html#lint-check-attributes +[`cold`]: attributes/codegen.html#the-cold-attribute +[lint check attributes]: attributes/diagnostics.html#lint-check-attributes [Range Expression]: expressions/range-expr.html [_Pattern_]: patterns.html diff --git a/src/items-and-attributes.md b/src/items-and-attributes.md deleted file mode 100644 index bd5018d69cc78..0000000000000 --- a/src/items-and-attributes.md +++ /dev/null @@ -1,7 +0,0 @@ -# Items and attributes - -Crates contain [items], each of which may have some number of -[attributes] attached to it. - -[items]: items.html -[attributes]: attributes.html diff --git a/src/items/extern-crates.md b/src/items/extern-crates.md index 69c7bde4a6d8f..f2c3be5ff57de 100644 --- a/src/items/extern-crates.md +++ b/src/items/extern-crates.md @@ -93,12 +93,18 @@ by using an underscore with the form `extern crate foo as _`. This may be useful for crates that only need to be linked, but are never referenced, and will avoid being reported as unused. -The [`#[macro_use]` attribute] will work as usual and import the macro names +The [`macro_use` attribute] works as usual and import the macro names into the macro-use prelude. +## The `no_link` attribute + +The *`no_link` attribute* may be specified on an `extern crate` item to +prevent linking the crate into the output. This is commonly used to load a +crate to access only its macros. + [IDENTIFIER]: identifiers.html [RFC 940]: https://github.com/rust-lang/rfcs/blob/master/text/0940-hyphens-considered-harmful.md -[`#[macro_use]` attribute]: macros-by-example.html#the-macro_use-attribute +[`macro_use` attribute]: macros-by-example.html#the-macro_use-attribute [`alloc`]: https://doc.rust-lang.org/alloc/ [`crate::`]: paths.html#crate [`no_implicit_prelude`]: items/modules.html#prelude-items diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index b4f16b881f43e..bdb9fc80608d8 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -42,16 +42,16 @@ Functions within external blocks may be called by Rust code, just like functions defined in Rust. The Rust compiler automatically translates between the Rust ABI and the foreign ABI. -Functions within external blocks may be variadic by specifying `...` after one -or more named arguments in the argument list: +A function declared in an extern block is implicitly `unsafe`. When coerced to +a function pointer, a function declared in an extern block has type `unsafe +extern "abi" for<'l1, ..., 'lm> fn(A1, ..., An) -> R`, where `'l1`, ... `'lm` +are its lifetime parameters, `A1`, ..., `An` are the declared types of its +parameters and `R` is the declared return type. -```rust,ignore -extern { - fn foo(x: i32, ...); -} -``` +It is `unsafe` to access a static item declared in an extern block, whether or +not it's mutable. -A number of [attributes] control the behavior of external blocks. +## ABI By default external blocks assume that the library they are calling uses the standard C ABI on the specific platform. Other ABIs may be specified using an @@ -92,29 +92,65 @@ Finally, there are some rustc-specific ABI strings: * `extern "platform-intrinsic"` -- Specific platform intrinsics -- like, for example, `sqrt` -- have this ABI. You should never have to deal with it. -The `link` attribute allows the name of the library to be specified. When -specified the compiler will attempt to link against the native library of the -specified name. +## Variadic functions + +Functions within external blocks may be variadic by specifying `...` after one +or more named arguments in the argument list: ```rust,ignore -#[link(name = "crypto")] -extern { } +extern { + fn foo(x: i32, ...); +} ``` -A function declared in an extern block is implicitly `unsafe`. When coerced to -a function pointer, a function declared in an extern block has type `unsafe -extern "abi" for<'l1, ..., 'lm> fn(A1, ..., An) -> R`, where `'l1`, ... `'lm` -are its lifetime parameters, `A1`, ..., `An` are the declared types of its -parameters and `R` is the declared return type. +## Attributes on extern blocks -It is `unsafe` to access a static item declared in an extern block, whether or -not it's mutable. +The following [attributes] control the behavior of external blocks. + +### The `link` attribute + +The *`link` attribute* specifies the name of a native library that the +compiler should link with. It uses the [_MetaListNameValueStr_] syntax to +specify its inputs. The `name` key is the name of the native library to link. +The `kind` key is an optional value which specifies the kind of library with +the following possible values: + +- `dylib` — Indicates a dynamic library. This is the default if `kind` is not + specified. +- `static` — Indicates a static library. +- `framework` — Indicates a macOS framework. This is only valid for macOS + targets. + +```rust,ignore +#[link(name = "crypto")] +extern { + // … +} + +#[link(name = "CoreFoundation", kind = "framework")] +extern { + // … +} +``` It is valid to add the `link` attribute on an empty extern block. You can use this to satisfy the linking requirements of extern blocks elsewhere in your code (including upstream crates) instead of adding the attribute to each extern block. +### The `link_name` attribute + +The `link_name` attribute may be specified on declarations inside an `extern` +block to indicate the symbol to import for the given function or static. It +uses the [_MetaNameValueStr_] syntax to specify the name of the symbol. + +```rust,ignore +extern { + #[link_name = "actual_symbol_name"] + fn name_in_rust(); +} +``` + [IDENTIFIER]: identifiers.html [_Abi_]: items/functions.html [_FunctionParam_]: items/functions.html @@ -122,8 +158,10 @@ block. [_FunctionReturnType_]: items/functions.html [_Generics_]: items/generics.html [_InnerAttribute_]: attributes.html +[_MetaListNameValueStr_]: attributes.html#meta-item-attribute-syntax +[_MetaNameValueStr_]: attributes.html#meta-item-attribute-syntax [_OuterAttribute_]: attributes.html [_Type_]: types.html#type-expressions [_Visibility_]: visibility-and-privacy.html [_WhereClause_]: items/generics.html#where-clauses -[attributes]: attributes.html#ffi-attributes +[attributes]: attributes.html diff --git a/src/items/functions.md b/src/items/functions.md index 9a0a682e46f73..33d71806d453b 100644 --- a/src/items/functions.md +++ b/src/items/functions.md @@ -207,7 +207,7 @@ fn test_only() { > function items. The attributes that have meaning on a function are [`cfg`], [`deprecated`], -[`doc`], `export_name`, `link_section`, `no_mangle`, [the lint check +[`doc`], [`export_name`], [`link_section`], [`no_mangle`], [the lint check attributes], [`must_use`], [the procedural macro attributes], [the testing attributes], and [the optimization hint attributes]. Functions also accept attributes macros. @@ -232,13 +232,16 @@ attributes macros. [Trait]: items/traits.html [attributes]: attributes.html [`cfg`]: conditional-compilation.html -[the lint check attributes]: attributes.html#lint-check-attributes +[the lint check attributes]: attributes/diagnostics.html#lint-check-attributes [the procedural macro attributes]: procedural-macros.html -[the testing attributes]: attributes.html#testing -[the optimization hint attributes]: attributes.html#optimization-hints -[`deprecated`]: attributes.html#deprecation -[`doc`]: attributes.html#documentation -[`must_use`]: attributes.html#must_use +[the testing attributes]: attributes/testing.html +[the optimization hint attributes]: attributes/codegen.html#optimization-hints +[`deprecated`]: attributes/diagnostics.html#the-deprecated-attribute +[`doc`]: ../rustdoc/the-doc-attribute.html +[`must_use`]: attributes/diagnostics.html#the-must_use-attribute [patterns]: patterns.html [`?Sized`]: trait-bounds.html#sized [trait bounds]: trait-bounds.html +[`export_name`]: abi.html#the-export_name-attribute +[`link_section`]: abi.html#the-link_section-attribute +[`no_mangle`]: abi.html#the-no_mangle-attribute diff --git a/src/items/implementations.md b/src/items/implementations.md index 8d6df033a7cc8..f06e6b49fa4d9 100644 --- a/src/items/implementations.md +++ b/src/items/implementations.md @@ -220,8 +220,8 @@ attributes]. [associated constants]: items/associated-items.html#associated-constants [attributes]: attributes.html [`cfg`]: conditional-compilation.html -[`deprecated`]: attributes.html#deprecation -[`doc`]: attributes.html#documentation +[`deprecated`]: attributes/diagnostics.html#the-deprecated-attribute +[`doc`]: ../rustdoc/the-doc-attribute.html [path]: paths.html -[the lint check attributes]: attributes.html#lint-check-attributes +[the lint check attributes]: attributes/diagnostics.html#lint-check-attributes [Unsafe traits]: items/traits.html#unsafe-traits diff --git a/src/items/modules.md b/src/items/modules.md index b12f915a2acf8..6784edfc3685a 100644 --- a/src/items/modules.md +++ b/src/items/modules.md @@ -65,7 +65,7 @@ alternately be expressed with `crate::util`'s contents in a file named > convention as it is more consistent, and avoids having many files named > `mod.rs` within a project. -### `path` Attribute +### The `path` attribute The directories and files used for loading external file modules can be influenced with the `path` attribute. @@ -144,11 +144,11 @@ The built-in attributes that have meaning on a function are [`cfg`], [_OuterAttribute_]: attributes.html [`#[macro_use]`]: macros-by-example.html#the-macro_use-attribute [`cfg`]: conditional-compilation.html -[`deprecated`]: attributes.html#deprecation -[`doc`]: attributes.html#documentation +[`deprecated`]: attributes/diagnostics.html#the-deprecated-attribute +[`doc`]: ../rustdoc/the-doc-attribute.html [IDENTIFIER]: identifiers.html [attribute]: attributes.html [items]: items.html [module path]: paths.html [prelude]: crates-and-source-files.html#preludes-and-no_std -[the lint check attributes]: attributes.html#lint-check-attributes +[the lint check attributes]: attributes/diagnostics.html#lint-check-attributes diff --git a/src/macros-by-example.md b/src/macros-by-example.md index 400259e7e7f30..c21075b4ac4da 100644 --- a/src/macros-by-example.md +++ b/src/macros-by-example.md @@ -307,8 +307,8 @@ imported this way are imported into the prelude of the crate, not textually, which means that they can be shadowed by any other name. While macros imported by `#[macro_use]` can be used before the import statement, in case of a conflict, the last macro imported wins. Optionally, a list of macros to import -can be specified; this is not supported when `#[macro_use]` is applied to a -module. +can be specified using the [_MetaListIdents_] syntax; this is not supported +when `#[macro_use]` is applied to a module. ```rust,ignore #[macro_use(lazy_static)] // Or #[macro_use] to import all macros. @@ -487,6 +487,7 @@ For more detail, see the [formal specification]. [_Item_]: items.html [_LiteralExpression_]: expressions/literal-expr.html [_MetaItem_]: attributes.html#meta-item-attribute-syntax +[_MetaListIdents_]: attributes.html#meta-item-attribute-syntax [_Pattern_]: patterns.html [_Statement_]: statements.html [_TokenTree_]: macros.html#macro-invocation diff --git a/src/procedural-macros.md b/src/procedural-macros.md index 7a9a600d87b57..5c522c35cef30 100644 --- a/src/procedural-macros.md +++ b/src/procedural-macros.md @@ -113,7 +113,7 @@ as `make_answer!{}`, `make_answer!();` or `make_answer![];`. ### Derive macros -*Derive macros* define new inputs for the `derive` [attribute]. These macros +*Derive macros* define new inputs for the [`derive` attribute]. These macros can create new [items] given the token stream of a [struct], [enum], or [union]. They can also define [derive macro helper attributes]. @@ -269,7 +269,7 @@ fn invoke4() {} [`TokenStream`]: ../proc_macro/struct.TokenStream.html [`TokenStream`s]: ../proc_macro/struct.TokenStream.html [`compile_error`]: ../std/macro.compile_error.html -[`derive`]: attributes.html#derive +[`derive` attribute]: attributes/derive.html [`proc_macro` crate]: ../proc_macro/index.html [Cargo's build scripts]: ../cargo/reference/build-scripts.html [Derive macros]: #derive-macros diff --git a/src/runtime.md b/src/runtime.md index 09fd888bfedc8..5a1f98b0abd7e 100644 --- a/src/runtime.md +++ b/src/runtime.md @@ -51,7 +51,29 @@ defaults to unwinding the stack but that can be [changed to abort the process][abort]. The standard library's panic behavior can be modified at runtime with the [set_hook] function. +## The `global_allocator` attribute + +The *`global_allocator` attribute* is used on a [static item] implementing the +[`GlobalAlloc`] trait to set the global allocator. + +## The `windows_subsystem` attribute + +The *`windows_subsystem` attribute* may be applied at the crate level to set +the [subsystem] when linking on a Windows target. It uses the +[_MetaNameValueStr_] syntax to specify the subsystem with a value of either +`console` or `windows`. This attribute is ignored on non-Windows targets, and +for non-`bin` [crate types]. + +```rust,ignore +#![windows_subsystem = "windows"] +``` + +[_MetaNameValueStr_]: attributes.html#meta-item-attribute-syntax +[`GlobalAlloc`]: ../alloc/alloc/trait.GlobalAlloc.html [`PanicInfo`]: ../core/panic/struct.PanicInfo.html [abort]: ../book/ch09-01-unrecoverable-errors-with-panic.html [attribute]: attributes.html +[crate types]: linkage.html [set_hook]: ../std/panic/fn.set_hook.html +[static item]: items/static-items.html +[subsystem]: https://msdn.microsoft.com/en-us/library/fcc1zstk.aspx diff --git a/src/statements.md b/src/statements.md index ab89cbd737d60..f5f4e565e732b 100644 --- a/src/statements.md +++ b/src/statements.md @@ -125,7 +125,7 @@ statement are [`cfg`], and [the lint check attributes]. [variables]: variables.html [outer attributes]: attributes.html [`cfg`]: conditional-compilation.html -[the lint check attributes]: attributes.html#lint-check-attributes +[the lint check attributes]: attributes/diagnostics.html#lint-check-attributes [pattern]: patterns.html [_ExpressionStatement_]: #expression-statements [_Expression_]: expressions.html diff --git a/src/type-layout.md b/src/type-layout.md index 9d56851bd5bbb..82ee95e566c28 100644 --- a/src/type-layout.md +++ b/src/type-layout.md @@ -112,9 +112,9 @@ Closures have no layout guarantees. All user-defined composite types (`struct`s, `enum`s, and `union`s) have a *representation* that specifies what the layout is for the type. -The possible representations for a type are the default representation, `C`, the -primitive representations, and `packed`. Multiple representations can be applied -to a single type. +The possible representations for a type are the default representation, `C`, +the primitive representations, `packed`, and `transparent`. Multiple +representations can be applied to a single type. The representation of a type can be changed by applying the `repr` attribute to it. The following example shows a struct with a `C` representation. @@ -258,8 +258,8 @@ layout is unspecified. ### Primitive representations The *primitive representations* are the representations with the same names as -the primitive integer types. That is: `u8`, `u16`, `u32`, `u64`, `usize`, `i8`, -`i16`, `i32`, `i64`, and `isize`. +the primitive integer types. That is: `u8`, `u16`, `u32`, `u64`, `u128`, +`usize`, `i8`, `i16`, `i32`, `i64`, `i128`, and `isize`. Primitive representations can only be applied to enumerations. diff --git a/src/types/closure.md b/src/types/closure.md index 785b78fbe8b40..51c6b0e50fbf3 100644 --- a/src/types/closure.md +++ b/src/types/closure.md @@ -174,4 +174,4 @@ Because captures are often by reference, the following general rules arise: [`Sized`]: special-types-and-traits.html#sized [`Sync`]: special-types-and-traits.html#sync [closure expression]: expressions/closure-expr.html -[derived]: attributes.html#derive +[derived]: attributes/derive.html diff --git a/src/types/struct.md b/src/types/struct.md index a398d1b91f4d6..1b57f971bb4ce 100644 --- a/src/types/struct.md +++ b/src/types/struct.md @@ -7,7 +7,7 @@ New instances of a `struct` can be constructed with a [struct expression]. The memory layout of a `struct` is undefined by default to allow for compiler optimizations like field reordering, but it can be fixed with the -`#[repr(...)]` attribute. In either case, fields may be given in any order in a +[`repr` attribute]. In either case, fields may be given in any order in a corresponding struct *expression*; the resulting `struct` value will always have the same memory layout. @@ -24,5 +24,6 @@ value that inhabits such a type. [^structtype]: `struct` types are analogous to `struct` types in C, the *record* types of the ML family, or the *struct* types of the Lisp family. +[`repr` attribute]: type-layout.html#representations [struct expression]: expressions/struct-expr.html [visibility modifiers]: visibility-and-privacy.html diff --git a/src/undocumented.md b/src/undocumented.md index 06d32dd2b5a37..a316a8e6b8e2b 100644 --- a/src/undocumented.md +++ b/src/undocumented.md @@ -21,5 +21,5 @@ to shrink! [Flexible target specification]: https://github.com/rust-lang/rfcs/pull/131 [Conditional compilation]: conditional-compilation.html [`dllimport`]: https://github.com/rust-lang/rfcs/pull/1717 -[FFI attributes]: attributes.html#ffi-attributes +[FFI attributes]: attributes.html [define `crt_link`]: https://github.com/rust-lang/rfcs/pull/1721