diff --git a/src/attributes.md b/src/attributes.md index 7294de6e2..abf36d415 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -107,6 +107,9 @@ 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 @@ -115,7 +118,6 @@ names have meaning. object being linked to defines `main`. - `no_start` - disable linking to the `native` crate, which specifies the "start" language item. -- `no_std` - disable linking to the `std` crate. - `recursion_limit` - Sets the maximum depth for potentially infinitely-recursive compile-time operations like auto-dereference or macro expansion. The default is @@ -130,14 +132,6 @@ names have meaning. [subsystem]: https://msdn.microsoft.com/en-us/library/fcc1zstk.aspx -## Module-only attributes - -- `no_implicit_prelude` - disable injecting `use std::prelude::*` in this - module. -- `path` - specifies the file to load the module from. `#[path="foo.rs"] mod - bar;` is equivalent to `mod bar { /* contents of foo.rs */ }`. The path is - taken relative to the directory that the current module is in. - ## FFI attributes On an `extern` block, the following attributes are interpreted: @@ -245,6 +239,17 @@ are transformed into `doc` attributes. See [The Rustdoc Book] for reference material on this attribute. +### `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 @@ -527,8 +532,12 @@ You can implement `derive` for your own traits through [procedural macros]. [_LiteralExpression_]: expressions/literal-expr.html [_SimplePath_]: paths.html#simple-paths +[`no_implicit_prelude`]: items/modules.html +[`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 [enum]: items/enumerations.html diff --git a/src/crates-and-source-files.md b/src/crates-and-source-files.md index 656ae574c..b2dd4f03f 100644 --- a/src/crates-and-source-files.md +++ b/src/crates-and-source-files.md @@ -20,9 +20,8 @@ Rust's semantics obey a *phase distinction* between compile-time and run-time.[^phase-distinction] Semantic rules that have a *static interpretation* govern the success or failure of compilation, while -semantic rules -that have a *dynamic interpretation* govern the behavior of the program at -run-time. +semantic rules that have a *dynamic interpretation* govern the behavior of the +program at run-time. The compilation model centers on artifacts called _crates_. Each compilation processes a single crate in source form, and if successful, produces a single @@ -66,22 +65,6 @@ apply to the crate as a whole. #![warn(non_camel_case_types)] ``` -A crate that contains a `main` [function] can be compiled to an executable. If a -`main` function is present, it 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. - - - The optional [_UTF8 byte order mark_] (UTF8BOM production) indicates that the file is encoded in UTF8. It can only occur at the beginning of the file and is ignored by the compiler. @@ -100,6 +83,48 @@ fn main() { } ``` +## Preludes and `no_std` + +All crates have a *prelude* that automatically inserts names from a specific +module, the *prelude module*, into scope of each [module] and an [`extern +crate]` into the crate root module. By default, the *standard prelude* is used. +The linked crate is [`std`] and the prelude module is [`std::prelude::v1`]. + +The prelude can be changed to the *core prelude* by using the `no_std` +[attribute] on the root crate module. The linked crate is [`core`] and the +prelude module is [`core::prelude::v1`]. Using the core prelude over the +standard prelude is useful when either the crate is targeting a platform that +does not support the standard library or is purposefully not using the +capabilities of the standard library. Those capabilities are mainly dynamic +memory allocation (e.g. `Box` and `Vec`) and file and network capabilities (e.g. +`std::fs` and `std::io`). + +
+ +Warning: Using `no_std` does not prevent the standard library from being linked +in. It is still valid to put `extern crate std;` into the crate and dependencies +can also link it in. + +
+ +## Main Functions + +A crate that contains a `main` [function] can be compiled to an executable. If a +`main` function is present, it 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. + + + [^phase-distinction]: This distinction would also exist in an interpreter. Static checks like syntactic analysis, type checking, and lints should happen before the program is executed regardless of when it is executed. @@ -108,15 +133,21 @@ fn main() { 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. -[module]: items/modules.html -[module path]: paths.html -[attributes]: attributes.html -[unit]: types.html#tuple-types [_InnerAttribute_]: attributes.html [_Item_]: items.html [_shebang_]: https://en.wikipedia.org/wiki/Shebang_(Unix) [_utf8 byte order mark_]: https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8 -[function]: items/functions.html [`Termination`]: ../std/process/trait.Termination.html -[where clauses]: items/generics.html#where-clauses +[`core`]: ../core/index.html +[`core::prelude::v1`]: ../core/preludce.index.html +[`std`]: ../std/index.html +[`std::prelude::v1`]: ../std/prelude/index.html +[`use` declaration]: items/use-declarations.html +[attribute]: attributes.html +[attributes]: attributes.html +[function]: items/functions.html +[module]: items/modules.html +[module path]: paths.html [trait or lifetime bounds]: trait-bounds.html +[unit]: types.html#tuple-types +[where clauses]: items/generics.html#where-clauses diff --git a/src/items/functions.md b/src/items/functions.md index 5fb071266..474cc95ad 100644 --- a/src/items/functions.md +++ b/src/items/functions.md @@ -157,8 +157,8 @@ fn test_only() { The attributes that have meaning on a function are [`cfg`], [`deprecated`], [`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]. +attributes], and [the optimization hint attributes]. Functions also accept +attributes macros. [IDENTIFIER]: identifiers.html [RAW_STRING_LITERAL]: tokens.html#raw-string-literals diff --git a/src/items/modules.md b/src/items/modules.md index c08b41071..da06a6dd7 100644 --- a/src/items/modules.md +++ b/src/items/modules.md @@ -21,15 +21,15 @@ mod math { type Complex = (f64, f64); fn sin(f: f64) -> f64 { /* ... */ -# panic!(); +# unimplemented!(); } fn cos(f: f64) -> f64 { /* ... */ -# panic!(); +# unimplemented!(); } fn tan(f: f64) -> f64 { /* ... */ -# panic!(); +# unimplemented!(); } } ``` @@ -68,10 +68,31 @@ mod thread { } ``` -[IDENTIFIER]: identifiers.html +Modules implicitly have some names in scope. These name are to built-in types, +macros imported with `#[macro_use]` on an extern crate, and by the crate's +[prelude]. These names are all made of a single identifier. These names are not +part of the module, so for example, any name `name`, `self::name` is not a +valid path. The names added by the [prelude] can be removed by placing the +`no_implicit_prelude` [attribute] onto the module. -[_InnerAttribute_]: attributes.html -[_OuterAttribute_]: attributes.html +## Attributes on Modules + +Modules, like all items, accept outer attributes. They also accept inner +attibutes: either after `{` for a module with a body, or at the beginning of the +source file, after the optional BOM and shebang. +The built-in attributes that have meaning on a function are [`cfg`], +[`deprecated`], [`doc`], [the lint check attributes], `path`, and +`no_implicit_prelude`. Modules also accept macro attributes. + +[_InnerAttribute_]: attributes.html [_Item_]: items.html +[_OuterAttribute_]: attributes.html +[`cfg`]: conditional-compilation.html +[`deprecated`]: attributes.html#deprecation +[`doc`]: attributes.html#documentation +[IDENTIFIER]: identifiers.html +[attribute]: attributes.html [items]: items.html +[prelude]: crates-and-source-files.html#preludes-and-no_std +[the lint check attributes]: attributes.html#lint-check-attributes