1# Preludes 2 3A *prelude* is a collection of names that are automatically brought into scope 4of every module in a crate. 5 6These prelude names are not part of the module itself: they are implicitly 7queried during [name resolution]. For example, even though something like 8[`Box`] is in scope in every module, you cannot refer to it as `self::Box` 9because it is not a member of the current module. 10 11There are several different preludes: 12 13- [Standard library prelude] 14- [Extern prelude] 15- [Language prelude] 16- [`macro_use` prelude] 17- [Tool prelude] 18 19## Standard library prelude 20 21The standard library prelude includes names from the [`std::prelude::v1`] 22module. If the [`no_std` attribute] is used, then it instead uses the names 23from the [`core::prelude::v1`] module. 24 25## Extern prelude 26 27External crates imported with [`extern crate`] in the root module or provided 28to the compiler (as with the `--extern` flag with `rustc`) are added to the 29*extern prelude*. If imported with an alias such as `extern crate orig_name as 30new_name`, then the symbol `new_name` is instead added to the prelude. 31 32The [`core`] crate is always added to the extern prelude. The [`std`] crate is 33added as long as the [`no_std` attribute] is not specified in the crate root. 34 35> **Edition Differences**: In the 2015 edition, crates in the extern prelude 36> cannot be referenced via [use declarations], so it is generally standard 37> practice to include `extern crate` declarations to bring them into scope. 38> 39> Beginning in the 2018 edition, [use declarations] can reference crates in 40> the extern prelude, so it is considered unidiomatic to use `extern crate`. 41 42> **Note**: Additional crates that ship with `rustc`, such as [`alloc`], and 43> [`test`], are not automatically included with the `--extern` flag when using 44> Cargo. They must be brought into scope with an `extern crate` declaration, 45> even in the 2018 edition. 46> 47> ```rust 48> extern crate alloc; 49> use alloc::rc::Rc; 50> ``` 51> 52> Cargo does bring in `proc_macro` to the extern prelude for proc-macro crates 53> only. 54 55<!-- 56See https://github.com/rust-lang/rust/issues/57288 for more about the 57alloc/test limitation. 58--> 59 60### The `no_std` attribute 61 62By default, the standard library is automatically included in the crate root 63module. The [`std`] crate is added to the root, along with an implicit 64[`macro_use` attribute] pulling in all macros exported from `std` into the 65[`macro_use` prelude]. Both [`core`] and [`std`] are added to the [extern 66prelude]. The [standard library prelude] includes everything from the 67[`std::prelude::v1`] module. 68 69The *`no_std` [attribute]* may be applied at the crate level to prevent the 70[`std`] crate from being automatically added into scope. It does three things: 71 72* Prevents `std` from being added to the [extern prelude](#extern-prelude). 73* Uses [`core::prelude::v1`] in the [standard library prelude] instead of 74 [`std::prelude::v1`]. 75* Injects the [`core`] crate into the crate root instead of [`std`], and pulls 76 in all macros exported from `core` in the [`macro_use` prelude]. 77 78> **Note**: Using the core prelude over the standard prelude is useful when 79> either the crate is targeting a platform that does not support the standard 80> library or is purposefully not using the capabilities of the standard 81> library. Those capabilities are mainly dynamic memory allocation (e.g. `Box` 82> and `Vec`) and file and network capabilities (e.g. `std::fs` and `std::io`). 83 84<div class="warning"> 85 86Warning: Using `no_std` does not prevent the standard library from being 87linked in. It is still valid to put `extern crate std;` into the crate and 88dependencies can also link it in. 89 90</div> 91 92## Language prelude 93 94The language prelude includes names of types and attributes that are built-in 95to the language. The language prelude is always in scope. It includes the following: 96 97* [Type namespace] 98 * [Boolean type] — `bool` 99 * [Textual types] — `char` and `str` 100 * [Integer types] — `i8`, `i16`, `i32`, `i64`, `i128`, `u8`, `u16`, `u32`, `u64`, `u128` 101 * [Machine-dependent integer types] — `usize` and `isize` 102 * [floating-point types] — `f32` and `f64` 103* [Macro namespace] 104 * [Built-in attributes] 105 106## `macro_use` prelude 107 108The `macro_use` prelude includes macros from external crates that were 109imported by the [`macro_use` attribute] applied to an [`extern crate`]. 110 111## Tool prelude 112 113The tool prelude includes tool names for external tools in the [type 114namespace]. See the [tool attributes] section for more details. 115 116## The `no_implicit_prelude` attribute 117 118The *`no_implicit_prelude` [attribute]* may be applied at the crate level or 119on a module to indicate that it should not automatically bring the [standard 120library prelude], [extern prelude], or [tool prelude] into scope for that 121module or any of its descendants. 122 123This attribute does not affect the [language prelude]. 124 125> **Edition Differences**: In the 2015 edition, the `no_implicit_prelude` 126> attribute does not affect the [`macro_use` prelude], and all macros exported 127> from the standard library are still included in the `macro_use` prelude. 128> Starting in the 2018 edition, it will remove the `macro_use` prelude. 129 130[`alloc`]: ../../alloc/index.html 131[`Box`]: ../../std/boxed/struct.Box.html 132[`core::prelude::v1`]: ../../core/prelude/index.html 133[`core`]: ../../core/index.html 134[`extern crate`]: ../items/extern-crates.md 135[`macro_use` attribute]: ../macros-by-example.md#the-macro_use-attribute 136[`macro_use` prelude]: #macro_use-prelude 137[`no_std` attribute]: #the-no_std-attribute 138[`no_std` attribute]: #the-no_std-attribute 139[`std::prelude::v1`]: ../../std/prelude/index.html 140[`std`]: ../../std/index.html 141[`test`]: ../../test/index.html 142[attribute]: ../attributes.md 143[Boolean type]: ../types/boolean.md 144[Built-in attributes]: ../attributes.md#built-in-attributes-index 145[extern prelude]: #extern-prelude 146[floating-point types]: ../types/numeric.md#floating-point-types 147[Integer types]: ../types/numeric.md#integer-types 148[Language prelude]: #language-prelude 149[Machine-dependent integer types]: ../types/numeric.md#machine-dependent-integer-types 150[Macro namespace]: namespaces.md 151[name resolution]: name-resolution.md 152[Standard library prelude]: #standard-library-prelude 153[Textual types]: ../types/textual.md 154[tool attributes]: ../attributes.md#tool-attributes 155[Tool prelude]: #tool-prelude 156[Type namespace]: namespaces.md 157[use declarations]: ../items/use-declarations.md 158