src/doc/reference/src/names/preludes.md

   1 # Preludes
   2
   3 A *prelude* is a collection of names that are automatically brought into scope
   4 of every module in a crate.
   5
   6 These prelude names are not part of the module itself, they are implicitly
   7 queried 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`
   9 because it is not a member of the current module.
  10
  11 There 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
  21 The standard library prelude includes names from the [`std::prelude::v1`]
  22 module. If the [`no_std` attribute] is used, then it instead uses the names
  23 from the [`core::prelude::v1`] module.
  24
  25 ## Extern prelude
  26
  27 External crates imported with [`extern crate`] in the root module or provided
  28 to 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
  30 new_name`, then the symbol `new_name` is instead added to the prelude.
  31
  32 The [`core`] crate is always added to the extern prelude. The [`std`] crate is
  33 added 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 <!--
  56 See https://github.com/rust-lang/rust/issues/57288 for more about the
  57 alloc/test limitation.
  58 -->
  59
  60 ### The `no_std` attribute
  61
  62 By default, the standard library is automatically included in the crate root
  63 module. 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
  66 prelude]. The [standard library prelude] includes everything from the
  67 [`std::prelude::v1`] module.
  68
  69 The *`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
  86 Warning: Using `no_std` does not prevent the standard library from being
  87 linked in. It is still valid to put `extern crate std;` into the crate and
  88 dependencies can also link it in.
  89
  90 </div>
  91
  92 ## Language prelude
  93
  94 The language prelude includes names of types and attributes that are built-in
  95 to 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
 108 The `macro_use` prelude includes macros from external crates that were
 109 imported by the [`macro_use` attribute] applied to an [`extern crate`].
 110
 111 ## Tool prelude
 112
 113 The tool prelude includes tool names for external tools in the [type
 114 namespace]. See the [tool attributes] section for more details.
 115
 116 ## The `no_implicit_prelude` attribute
 117
 118 The *`no_implicit_prelude` [attribute]* may be applied at the crate level or
 119 on a module to indicate that it should not automatically bring the [standard
 120 library prelude], [extern prelude], or [tool prelude] into scope for that
 121 module or any of its descendants.
 122
 123 This 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