Merge pull request rust-lang#455 from ehuss/extern-crate

`extern crate` changes.

src/crates-and-source-files.md

@@ -87,7 +87,7 @@ fn main() {
 
 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.
+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`
@@ -140,6 +140,7 @@ type must  be one of the following:
 [`Termination`]: ../std/process/trait.Termination.html
 [`core`]: ../core/index.html
 [`core::prelude::v1`]: ../core/prelude/index.html
+[`extern crate`]: items/extern-crates.html
 [`std`]: ../std/index.html
 [`std::prelude::v1`]: ../std/prelude/index.html
 [`use` declaration]: items/use-declarations.html

src/items/extern-crates.md

@@ -5,16 +5,16 @@
 > &nbsp;&nbsp; `extern` `crate` [IDENTIFIER]&nbsp;(`as` [IDENTIFIER])<sup>?</sup> `;`
 
 An _`extern crate` declaration_ specifies a dependency on an external crate.
-The external crate is then bound into the declaring scope as the `ident`
-provided in the `extern_crate_decl`.
+The external crate is then bound into the declaring scope as the [identifier]
+provided in the `extern crate` declaration.
 
 The external crate is resolved to a specific `soname` at compile time, and a
 runtime linkage requirement to that `soname` is passed to the linker for
 loading at runtime. The `soname` is resolved at compile time by scanning the
 compiler's library path and matching the optional `crateid` provided against
 the `crateid` attributes that were declared on the external crate when it was
 compiled. If no `crateid` is provided, a default `name` attribute is assumed,
-equal to the `ident` given in the `extern_crate_decl`.
+equal to the [identifier] given in the `extern crate` declaration.
 
 Three examples of `extern crate` declarations:
 
@@ -38,6 +38,51 @@ Here is an example:
 extern crate hello_world; // hyphen replaced with an underscore
 ```
 
-[RFC 940]: https://github.com/rust-lang/rfcs/blob/master/text/0940-hyphens-considered-harmful.md
+## Extern Prelude
+
+External crates provided to the compiler are added to the "extern prelude"
+which exposes the crate names into lexical scope of every module without the
+need for specifying `extern crate`.
+
+> **Edition Differences**: In the 2015 edition, crates in the extern prelude
+> cannot be referenced via [use declarations], so it is generally standard
+> practice to include `extern crate` declarations to bring them into scope.
+>
+> Beginning in the 2018 edition, [use declarations] can reference crates in
+> the extern prelude, so it is considered unidiomatic to use `extern crate`.
+
+> **Note**: Additional crates that ship with `rustc`, such as [`proc_macro`],
+> [`alloc`], and [`test`], currently aren't available in the extern prelude
+> and must be brought into scope with an `extern crate` declaration, even in
+> the 2018 edition. `use` paths must reference the `extern crate` item (such
+> as using [`crate::`] or [`self::`] path prefixes).
+>
+> ```rust
+> extern crate proc_macro;
+> // Cannot reference `proc_macro` directly because it is not in the extern prelude.
+> // use proc_macro::TokenStream;
+> // Instead, you must reference the item in scope from the `extern crate`
+> // declaration.
+> use self::proc_macro::TokenStream;
+> ```
+
+<!--
+Possible upcoming changes that will change this:
+
+The `extern_crate_item_prelude` unstable feature allows `extern crate` to
+update the extern prelude in certain situations, see
+https://github.com/rust-lang/rust/pull/54658
+
+Unstable `--extern proc_macro` flag that would force the crate into the
+extern prelude.
+    https://github.com/rust-lang/rust/pull/54116
+-->
 
 [IDENTIFIER]: identifiers.html
+[RFC 940]: https://github.com/rust-lang/rfcs/blob/master/text/0940-hyphens-considered-harmful.md
+[`alloc`]: https://doc.rust-lang.org/alloc/
+[`crate::`]: paths.html#crate
+[`proc_macro`]: https://doc.rust-lang.org/proc_macro/
+[`self::`]: paths.html#self
+[`test`]: https://doc.rust-lang.org/test/
+[use declarations]: items/use-declarations.html