Skip to content

Commit

Permalink
Merge pull request #509 from ehuss/extern_crate_item_prelude
Browse files Browse the repository at this point in the history
Document extern_crate_item_prelude
  • Loading branch information
Centril authored Jan 13, 2019
2 parents 315c089 + 0ec21f0 commit 1c775a1
Show file tree
Hide file tree
Showing 2 changed files with 22 additions and 20 deletions.
2 changes: 1 addition & 1 deletion src/attributes.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
40 changes: 21 additions & 19 deletions src/items/extern-crates.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 imported with `extern crate orig_name as
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 in the crate root.

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
Expand All @@ -52,28 +60,20 @@ need for specifying `extern crate`.
> 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).
> [`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;
> ```
<!--
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
The proc_macro/alloc/test limitation may be lifted if the `--extern`
flag is stabilized and used. See tracking issue
https://github.com/rust-lang/rust/issues/57288 and the unstable
`--extern` flag added in https://github.com/rust-lang/rust/pull/54116.
-->
## Underscore Imports
Expand All @@ -91,6 +91,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/
Expand Down

0 comments on commit 1c775a1

Please sign in to comment.