Skip to content

Commit 957c82d

Browse files
committed
Update situations when extern crate is needed.
1 parent 3f9acdf commit 957c82d

File tree

1 file changed

+34
-20
lines changed

1 file changed

+34
-20
lines changed

src/rust-2018/module-system/path-clarity.md

Lines changed: 34 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -65,26 +65,40 @@ keep doing what you were doing there as well.
6565
#### An exception
6666

6767
There's one exception to this rule, and that's the "sysroot" crates. These are the
68-
crates distributed with Rust itself. We'd eventually like to remove the requirement
69-
for `extern crate` for them as well, but it hasn't shipped yet.
70-
71-
You'll need to use `extern crate` for:
72-
73-
* `proc_macro`
74-
75-
Additionally, you would need to use it for:
76-
77-
* `core`
78-
* `std`
79-
80-
However, `extern crate std;` is already implicit, and with `#![no_std]`,
81-
`extern crate core;` is already implicit. You'll only need these in highly
82-
specialized situations.
83-
84-
Finally, on nightly, you'll need it for crates like:
85-
86-
* `alloc`
87-
* `test`
68+
crates distributed with Rust itself.
69+
70+
Usually these are only needed in very specialized situations. Starting in
71+
1.41, `rustc` accepts the `--extern=CRATE_NAME` flag which automatically adds
72+
the given crate name in a way similar to `extern crate`. Build tools may use
73+
this to inject sysroot crates into the crate's prelude. Cargo does not have a
74+
general way to express this, though it uses it for `proc_macro` crates.
75+
76+
Some examples of needing to explicitly import sysroot crates are:
77+
78+
* [`std`]: Usually this is not neccesary, because `std` is automatically
79+
imported unless the crate is marked with [`#![no_std]`][no_std].
80+
* [`core`]: Usually this is not necessary, because `core` is automatically
81+
imported, unless the crate is marked with [`#![no_core]`][no_core]. For
82+
example, some of the internal crates used by the standard library itself
83+
need this.
84+
* [`proc_macro`]: This is automatically imported by Cargo if it is a
85+
proc-macro crate starting in 1.42. `extern crate proc_macro;` would be
86+
needed if you want to support older releases, or if using another build tool
87+
that does not pass the appropriate `--extern` flags to `rustc`.
88+
* [`alloc`]: Items in the `alloc` crate are usually accessed via re-exports in
89+
the `std` crate. If you are working with a `no_std` crate that supports
90+
allocation, then you may need to explicitly import `alloc`.
91+
* [`test`]: This is only available on the [nightly channel], and is usually
92+
only used for the unstable benchmark support.
93+
94+
[`alloc`]: ../../../alloc/index.html
95+
[`core`]: ../../../core/index.html
96+
[`proc_macro`]: ../../../proc_macro/index.html
97+
[`std`]: ../../../std/index.html
98+
[`test`]: ../../../test/index.html
99+
[nightly channel]: ../../../book/appendix-07-nightly-rust.html
100+
[no_core]: https://github.com/rust-lang/rust/issues/29639
101+
[no_std]: ../../../reference/crates-and-source-files.html#preludes-and-no_std
88102

89103
#### Macros
90104

0 commit comments

Comments
 (0)