From 32ff31db7cd0ab2d5d3c989b3393ba54093726c4 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 8 Oct 2018 16:00:03 -0700 Subject: [PATCH 1/2] `extern crate` changes. Stabilization PR: https://github.com/rust-lang/rust/pull/54403 --- src/crates-and-source-files.md | 3 +- src/items/extern-crates.md | 52 +++++++++++++++++++++++++++++++--- 2 files changed, 50 insertions(+), 5 deletions(-) diff --git a/src/crates-and-source-files.md b/src/crates-and-source-files.md index 4b3e729e34652..637f003f827f8 100644 --- a/src/crates-and-source-files.md +++ b/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 diff --git a/src/items/extern-crates.md b/src/items/extern-crates.md index 922e128c5ba06..9d8b47c2383b4 100644 --- a/src/items/extern-crates.md +++ b/src/items/extern-crates.md @@ -5,8 +5,8 @@ >    `extern` `crate` [IDENTIFIER] (`as` [IDENTIFIER])? `;` 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 @@ -14,7 +14,7 @@ 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,50 @@ 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 + +All external crates are available in 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; +> ``` + + [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 From 8fe63a9730ad00862649351a85c9fa4140ab0217 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 29 Oct 2018 12:43:36 -0700 Subject: [PATCH 2/2] Tweak extern prelude wording. --- src/items/extern-crates.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/src/items/extern-crates.md b/src/items/extern-crates.md index 9d8b47c2383b4..078cc7b5e084d 100644 --- a/src/items/extern-crates.md +++ b/src/items/extern-crates.md @@ -40,9 +40,9 @@ extern crate hello_world; // hyphen replaced with an underscore ## Extern Prelude -All external crates are available in the "extern prelude" which exposes the -crate names into lexical scope of every module without the need for specifying -`extern crate`. +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 @@ -69,8 +69,9 @@ crate names into lexical scope of every module without the need for specifying