r[names.preludes]

Preludes

r[names.preludes.intro] A prelude is a collection of names that are automatically brought into scope of every module in a crate.

These prelude names are not part of the module itself: they are implicitly queried during name resolution. For example, even though something like [Box] is in scope in every module, you cannot refer to it as self::Box because it is not a member of the current module.

r[names.preludes.kinds] There are several different preludes:

• Standard library prelude
• Extern prelude
• Language prelude
• macro_use prelude
• Tool prelude

r[names.preludes.std]

Standard library prelude

r[names.preludes.std.intro] Each crate has a standard library prelude, which consists of the names from a single standard library module.

r[names.preludes.std.module] The module used depends on the crate's edition, and on whether the no_std attribute is applied to the crate:

Edition	no_std not applied	no_std applied
2015	[std::prelude::rust_2015]	[core::prelude::rust_2015]
2018	[std::prelude::rust_2018]	[core::prelude::rust_2018]
2021	[std::prelude::rust_2021]	[core::prelude::rust_2021]
2024	[std::prelude::rust_2024]	[core::prelude::rust_2024]

[!NOTE] [std::prelude::rust_2015] and [std::prelude::rust_2018] have the same contents as [std::prelude::v1].

[core::prelude::rust_2015] and [core::prelude::rust_2018] have the same contents as [core::prelude::v1].

r[names.preludes.extern]

Extern prelude

r[names.preludes.extern.intro] 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. If imported with an alias such as extern crate orig_name as new_name, then the symbol new_name is instead added to the prelude.

r[names.preludes.extern.core] The [core] crate is always added to the extern prelude.

r[names.preludes.extern.std] The [std] crate is added as long as the no_std attribute is not specified in the crate root.

r[names.preludes.extern.edition2018]

[!EDITION-2018] 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 [alloc], and test, are not automatically included with the --extern flag when using Cargo. They must be brought into scope with an extern crate declaration, even in the 2018 edition.

extern crate alloc;
use alloc::rc::Rc;

Cargo does bring in proc_macro to the extern prelude for proc-macro crates only.

r[names.preludes.extern.no_std]

The no_std attribute

r[names.preludes.extern.no_std.intro] The no_std [attribute][attributes] causes the [std] crate to not be linked automatically, the standard library prelude to instead use the core prelude, and the macro_use prelude to instead use the macros exported from the core crate.

[!EXAMPLE]

#![no_std]

[!NOTE] Using no_std is useful when either the crate is targeting a platform that does not support the standard library or is purposefully not using the capabilities of the standard library. Those capabilities are mainly dynamic memory allocation (e.g. Box and Vec) and file and network capabilities (e.g. std::fs and std::io).

[!WARNING] Using no_std does not prevent the standard library from being linked. It is still valid to write extern crate std in the crate or in one of its dependencies; this will cause the compiler to link the std crate into the program.

r[names.preludes.extern.no_std.syntax] The no_std attribute uses the [MetaWord] syntax.

r[names.preludes.extern.no_std.allowed-positions] The no_std attribute may only be applied to the crate root.

r[names.preludes.extern.no_std.duplicates] The no_std attribute may be used any number of times on a form.

[!NOTE] rustc lints against any use following the first.

r[names.preludes.extern.no_std.module] The no_std attribute changes the standard library prelude to use the core prelude instead of the std prelude.

r[names.preludes.extern.no_std.macro_use] By default, all macros exported from the std crate are added to the macro_use prelude. If the no_std attribute is specified, then all macros exported from the core crate are placed into the macro_use prelude instead.

r[names.preludes.extern.no_std.edition2018]

[!EDITION-2018] Before the 2018 edition, std is injected into the crate root by default. If no_std is specified, core is injected instead. Starting with the 2018 edition, regardless of no_std being specified, neither is injected into the crate root.

r[names.preludes.lang]

Language prelude

r[names.preludes.lang.intro] The language prelude includes names of types and attributes that are built-in to the language. The language prelude is always in scope.

r[names.preludes.lang.entities] It includes the following:

• Type namespace
  • Boolean type --- bool
  • Textual types --- char and str
  • Integer types --- i8, i16, i32, i64, i128, u8, u16, u32, u64, u128
  • Machine-dependent integer types --- usize and isize
  • floating-point types --- f32 and f64
• Macro namespace
  • Built-in attributes
  • [Built-in derive macros][attributes.derive.built-in]

r[names.preludes.macro_use]

macro_use prelude

r[names.preludes.macro_use.intro] The macro_use prelude includes macros from external crates that were imported by the macro_use attribute applied to an extern crate.

r[names.preludes.tool]

Tool prelude

r[names.preludes.tool.intro] The tool prelude includes tool names for external tools in the type namespace. See the tool attributes section for more details.

r[names.preludes.no_implicit_prelude]

The no_implicit_prelude attribute

r[names.preludes.no_implicit_prelude.intro] The no_implicit_prelude attribute is used to prevent implicit preludes from being brought into scope.

[!EXAMPLE]

// The attribute can be applied to the crate root to affect
// all modules.
#![no_implicit_prelude]

// Or it can be applied to a module to only affect that module
// and its descendants.
#[no_implicit_prelude]
mod example {
    // ...
}

r[names.preludes.no_implicit_prelude.syntax] The no_implicit_prelude attribute uses the [MetaWord] syntax.

r[names.preludes.no_implicit_prelude.allowed-positions] The no_implicit_prelude attribute may only be applied to the crate or to a module.

[!NOTE] rustc ignores use in other positions but lints against it. This may become an error in the future.

r[names.preludes.no_implicit_prelude.duplicates] The no_implicit_prelude attribute may be used any number of times on a form.

[!NOTE] rustc lints against any use following the first.

r[names.preludes.no_implicit_prelude.excluded-preludes] The no_implicit_prelude attribute prevents the standard library prelude, extern prelude, macro_use prelude, and the tool prelude from being brought into scope for the module and its descendants.

r[names.preludes.no_implicit_prelude.lang] The no_implicit_prelude attribute does not affect the language prelude.

r[names.preludes.no_implicit_prelude.edition2018]

[!EDITION-2018] In the 2015 edition, the no_implicit_prelude attribute does not affect the macro_use prelude, and all macros exported from the standard library are still included in the macro_use prelude. Starting in the 2018 edition, the attribute does remove the macro_use prelude.