Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document extern_crate_item_prelude #509

Merged
merged 4 commits into from
Jan 13, 2019
Merged

Document extern_crate_item_prelude #509

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7a0ac86
Document extern_crate_item_prelude
ehuss Jan 13, 2019
15fc5d5
Clarify not "renamed".
Centril Jan 13, 2019
fc251f9
Apply suggestions from code review
Centril Jan 13, 2019
0ec21f0
Fix note about sysroot crates and extern prelude.
ehuss Jan 13, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/attributes.md
View file
Open in desktop
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
39 changes: 24 additions & 15 deletions src/items/extern-crates.md
View file
Open in desktop
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 renamed as in `extern crate orig_name as
ehuss marked this conversation as resolved.
Show resolved Hide resolved
new_name`, then the symbol `new_name` is added to the prelude.
ehuss marked this conversation as resolved.
Show resolved Hide resolved

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.
ehuss marked this conversation as resolved.
Show resolved Hide resolved

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 @@ -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
ehuss marked this conversation as resolved.
Show resolved Hide resolved
> 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).
Centril marked this conversation as resolved.
Show resolved Hide resolved
Centril marked this conversation as resolved.
Show resolved Hide resolved
>
> ```rust
> extern crate proc_macro;
Expand All @@ -67,13 +77,10 @@ need for specifying `extern crate`.
> ```

<!--
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 +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/
Expand Down