Skip to content

extern crate changes. #455

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

Merged
merged 2 commits into from
Nov 1, 2018
Merged

extern crate changes. #455

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
32ff31d
`extern crate` changes.
ehuss Oct 8, 2018
8fe63a9
Tweak extern prelude wording.
ehuss Oct 29, 2018
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
3 changes: 2 additions & 1 deletion src/crates-and-source-files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down Expand Up @@ -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
Expand Down
53 changes: 49 additions & 4 deletions src/items/extern-crates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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