From 7a0ac867d96419c0582cfd2b4d4ca8ec01705517 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 13 Jan 2019 09:50:56 -0800 Subject: [PATCH 1/4] Document extern_crate_item_prelude --- src/attributes.md | 2 +- src/items/extern-crates.md | 39 +++++++++++++++++++++++--------------- 2 files changed, 25 insertions(+), 16 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index 87fd9660b..f0452c3df 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -554,7 +554,7 @@ 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_implicit_prelude`]: items/modules.html#prelude-items [`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 diff --git a/src/items/extern-crates.md b/src/items/extern-crates.md index 3c61ce220..b94284e54 100644 --- a/src/items/extern-crates.md +++ b/src/items/extern-crates.md @@ -40,9 +40,17 @@ extern crate hello_world; // hyphen replaced with an underscore ## 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`. +External crates imported with `extern crate` in the root module or provided to +the compiler (as with the `--extern` flag with `rustc`) are added to the +"extern prelude". Crates in the extern prelude are in scope in the entire +crate, including inner modules. If renamed as in `extern crate orig_name as +new_name`, then the symbol `new_name` is added to the prelude. + +The `core` crate is always added to the extern prelude. The `std` crate +is added as long as the [`no_std`] attribute is not specified. + +The [`no_implicit_prelude`] attribute can be used on a module to disable +prelude lookups within that module. > **Edition Differences**: In the 2015 edition, crates in the extern prelude > cannot be referenced via [use declarations], so it is generally standard @@ -51,11 +59,13 @@ need for specifying `extern crate`. > 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). +> **Note**: Crates not explicitly named with the `--extern` flag with `rustc` +> are not included in the extern prelude. This means that 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; @@ -67,13 +77,10 @@ need for specifying `extern crate`. > ``` ## Underscore Imports @@ -91,6 +98,8 @@ into the macro-use prelude. [`#[macro_use]` attribute]: attributes.html#macro-related-attributes [`alloc`]: https://doc.rust-lang.org/alloc/ [`crate::`]: paths.html#crate +[`no_implicit_prelude`]: items/modules.html#prelude-items +[`no_std`]: crates-and-source-files.html#preludes-and-no_std [`proc_macro`]: https://doc.rust-lang.org/proc_macro/ [`self::`]: paths.html#self [`test`]: https://doc.rust-lang.org/test/ From 15fc5d5643eb27d7274cf194a9ac53f43d94ed66 Mon Sep 17 00:00:00 2001 From: Mazdak Farrokhzad Date: Sun, 13 Jan 2019 10:59:19 -0800 Subject: [PATCH 2/4] Clarify not "renamed". Co-Authored-By: ehuss --- src/items/extern-crates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/items/extern-crates.md b/src/items/extern-crates.md index b94284e54..f52f531be 100644 --- a/src/items/extern-crates.md +++ b/src/items/extern-crates.md @@ -43,7 +43,7 @@ extern crate hello_world; // hyphen replaced with an underscore External crates imported with `extern crate` in the root module or provided to the compiler (as with the `--extern` flag with `rustc`) are added to the "extern prelude". Crates in the extern prelude are in scope in the entire -crate, including inner modules. If renamed as in `extern crate orig_name as +crate, including inner modules. If imported with `extern crate orig_name as new_name`, then the symbol `new_name` is added to the prelude. The `core` crate is always added to the extern prelude. The `std` crate From fc251f9cfb4e2695ad934b4f4609de0852e6ed6f Mon Sep 17 00:00:00 2001 From: Mazdak Farrokhzad Date: Sun, 13 Jan 2019 11:01:24 -0800 Subject: [PATCH 3/4] Apply suggestions from code review Co-Authored-By: ehuss --- src/items/extern-crates.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/items/extern-crates.md b/src/items/extern-crates.md index f52f531be..f1d228a86 100644 --- a/src/items/extern-crates.md +++ b/src/items/extern-crates.md @@ -44,10 +44,10 @@ External crates imported with `extern crate` in the root module or provided to the compiler (as with the `--extern` flag with `rustc`) are added to the "extern prelude". Crates in the extern prelude are in scope in the entire crate, including inner modules. If imported with `extern crate orig_name as -new_name`, then the symbol `new_name` is added to the prelude. +new_name`, then the symbol `new_name` is instead added to the prelude. The `core` crate is always added to the extern prelude. The `std` crate -is added as long as the [`no_std`] attribute is not specified. +is added as long as the [`no_std`] attribute is not specified in the crate root. The [`no_implicit_prelude`] attribute can be used on a module to disable prelude lookups within that module. @@ -60,7 +60,7 @@ prelude lookups within that module. > the extern prelude, so it is considered unidiomatic to use `extern crate`. > **Note**: Crates not explicitly named with the `--extern` flag with `rustc` -> are not included in the extern prelude. This means that additional crates +> are not included in the extern prelude. As a result, 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` From 0ec21f01eb4fb92bdaab4f285bd901ef57076ad0 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 13 Jan 2019 11:19:23 -0800 Subject: [PATCH 4/4] Fix note about sysroot crates and extern prelude. --- src/items/extern-crates.md | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/src/items/extern-crates.md b/src/items/extern-crates.md index f1d228a86..6c3dcf90c 100644 --- a/src/items/extern-crates.md +++ b/src/items/extern-crates.md @@ -59,21 +59,14 @@ prelude lookups within that module. > Beginning in the 2018 edition, [use declarations] can reference crates in > the extern prelude, so it is considered unidiomatic to use `extern crate`. -> **Note**: Crates not explicitly named with the `--extern` flag with `rustc` -> are not included in the extern prelude. As a result, 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). +> **Note**: Additional crates that ship with `rustc`, such as [`proc_macro`], +> [`alloc`], and [`test`], are not automatically included with the `--extern` +> flag when using Cargo. They must be brought into scope with an `extern +> crate` declaration, even in the 2018 edition. > > ```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; +> use proc_macro::TokenStream; > ```