Document preludes

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

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`
-<!-- * `!` -->
-<!-- * Result<!, E> where E: Error` -->
-
-> Note: The implementation of which return types are allowed is determined by
-> the unstable [`Termination`] trait.
-
-<!-- If the previous section needs updating (from "must take no arguments"
-  onwards, also update it in the attributes.md file, testing section -->
-
 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`).
+
+<div class="warning">
+
+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.
+
+</div>
+
+## 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`
+<!-- * `!` -->
+<!-- * Result<!, E> where E: Error` -->
+
+> Note: The implementation of which return types are allowed is determined by
+> the unstable [`Termination`] trait.
+
+<!-- If the previous section needs updating (from "must take no arguments"
+  onwards, also update it in the attributes.md file, testing section -->
+
 [^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

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

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