]>
Commit | Line | Data |
---|---|---|
1a4d82fc JJ |
1 | //! # The Rust Core Library |
2 | //! | |
92a42be0 | 3 | //! The Rust Core Library is the dependency-free[^free] foundation of [The |
1a4d82fc JJ |
4 | //! Rust Standard Library](../std/index.html). It is the portable glue |
5 | //! between the language and its libraries, defining the intrinsic and | |
6 | //! primitive building blocks of all Rust code. It links to no | |
7 | //! upstream libraries, no system libraries, and no libc. | |
8 | //! | |
92a42be0 SL |
9 | //! [^free]: Strictly speaking, there are some symbols which are needed but |
10 | //! they aren't always necessary. | |
11 | //! | |
1a4d82fc JJ |
12 | //! The core library is *minimal*: it isn't even aware of heap allocation, |
13 | //! nor does it provide concurrency or I/O. These things require | |
14 | //! platform integration, and this library is platform-agnostic. | |
15 | //! | |
1a4d82fc JJ |
16 | //! # How to use the core library |
17 | //! | |
5bcae85e SL |
18 | //! Please note that all of these details are currently not considered stable. |
19 | //! | |
1a4d82fc JJ |
20 | // FIXME: Fill me in with more detail when the interface settles |
21 | //! This library is built on the assumption of a few existing symbols: | |
22 | //! | |
23 | //! * `memcpy`, `memcmp`, `memset` - These are core memory routines which are | |
24 | //! often generated by LLVM. Additionally, this library can make explicit | |
25 | //! calls to these functions. Their signatures are the same as found in C. | |
26 | //! These functions are often provided by the system libc, but can also be | |
9fa01778 | 27 | //! provided by the [compiler-builtins crate](https://crates.io/crates/compiler_builtins). |
1a4d82fc | 28 | //! |
041b39d2 XL |
29 | //! * `rust_begin_panic` - This function takes four arguments, a |
30 | //! `fmt::Arguments`, a `&'static str`, and two `u32`'s. These four arguments | |
5bcae85e | 31 | //! dictate the panic message, the file at which panic was invoked, and the |
041b39d2 XL |
32 | //! line and column inside the file. It is up to consumers of this core |
33 | //! library to define this panic function; it is only required to never | |
94b46f34 | 34 | //! return. This requires a `lang` attribute named `panic_impl`. |
9e0c209e SL |
35 | //! |
36 | //! * `rust_eh_personality` - is used by the failure mechanisms of the | |
37 | //! compiler. This is often mapped to GCC's personality function, but crates | |
38 | //! which do not trigger a panic can be assured that this function is never | |
39 | //! called. The `lang` attribute is called `eh_personality`. | |
1a4d82fc JJ |
40 | |
41 | // Since libcore defines many fundamental lang items, all tests live in a | |
42 | // separate crate, libcoretest, to avoid bizarre issues. | |
83c7162d XL |
43 | // |
44 | // Here we explicitly #[cfg]-out this whole crate when testing. If we don't do | |
45 | // this, both the generated test artifact and the linked libtest (which | |
46 | // transitively includes libcore) will both define the same set of lang items, | |
47 | // and this will cause the E0152 "duplicate lang item found" error. See | |
48 | // discussion in #50466 for details. | |
49 | // | |
50 | // This cfg won't affect doc tests. | |
51 | #![cfg(not(test))] | |
1a4d82fc | 52 | |
92a42be0 | 53 | #![stable(feature = "core", since = "1.6.0")] |
9fa01778 | 54 | #![doc(html_root_url = "https://doc.rust-lang.org/nightly/", |
e9174d1e | 55 | html_playground_url = "https://play.rust-lang.org/", |
92a42be0 SL |
56 | issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/", |
57 | test(no_crate_inject, attr(deny(warnings))), | |
58 | test(attr(allow(dead_code, deprecated, unused_variables, unused_mut))))] | |
e9174d1e | 59 | #![no_core] |
9fa01778 XL |
60 | |
61 | #![warn(deprecated_in_future)] | |
62 | #![warn(missing_docs)] | |
9fa01778 | 63 | #![warn(missing_debug_implementations)] |
48663c56 | 64 | #![deny(intra_doc_link_resolution_failure)] // rustdoc is run without -D warnings |
48663c56 | 65 | #![allow(explicit_outlives_requirements)] |
e1599b0c | 66 | #![allow(incomplete_features)] |
1a4d82fc | 67 | |
e9174d1e | 68 | #![feature(allow_internal_unstable)] |
94b46f34 | 69 | #![feature(arbitrary_self_types)] |
a7813a04 | 70 | #![feature(asm)] |
dc9dc135 | 71 | #![feature(bound_cloned)] |
cc61c64b | 72 | #![feature(cfg_target_has_atomic)] |
e9174d1e SL |
73 | #![feature(concat_idents)] |
74 | #![feature(const_fn)] | |
b7449926 | 75 | #![feature(const_fn_union)] |
416331ca | 76 | #![feature(const_generics)] |
60c5eb7d XL |
77 | #![cfg_attr(not(bootstrap), feature(const_ptr_offset_from))] |
78 | #![cfg_attr(not(bootstrap), feature(const_type_name))] | |
416331ca XL |
79 | #![feature(custom_inner_attributes)] |
80 | #![feature(decl_macro)] | |
0531ce1d XL |
81 | #![feature(doc_cfg)] |
82 | #![feature(doc_spotlight)] | |
83c7162d | 83 | #![feature(extern_types)] |
e9174d1e | 84 | #![feature(fundamental)] |
62682a34 | 85 | #![feature(intrinsics)] |
9fa01778 | 86 | #![feature(is_sorted)] |
0731742a | 87 | #![feature(iter_once_with)] |
62682a34 | 88 | #![feature(lang_items)] |
0531ce1d | 89 | #![feature(link_llvm_intrinsics)] |
cc61c64b | 90 | #![feature(never_type)] |
0bf4aa26 | 91 | #![feature(nll)] |
0531ce1d | 92 | #![feature(exhaustive_patterns)] |
e9174d1e | 93 | #![feature(no_core)] |
60c5eb7d | 94 | #![cfg_attr(bootstrap, feature(on_unimplemented))] |
c34b1796 | 95 | #![feature(optin_builtin_traits)] |
cc61c64b | 96 | #![feature(prelude_import)] |
9cc50fc6 | 97 | #![feature(repr_simd, platform_intrinsics)] |
54a0048b | 98 | #![feature(rustc_attrs)] |
60c5eb7d | 99 | #![cfg_attr(bootstrap, feature(rustc_const_unstable))] |
0531ce1d | 100 | #![feature(simd_ffi)] |
54a0048b | 101 | #![feature(specialization)] |
e9174d1e | 102 | #![feature(staged_api)] |
9fa01778 | 103 | #![feature(std_internals)] |
0531ce1d | 104 | #![feature(stmt_expr_attributes)] |
60c5eb7d | 105 | #![cfg_attr(not(bootstrap), feature(track_caller))] |
416331ca | 106 | #![feature(transparent_unions)] |
e9174d1e | 107 | #![feature(unboxed_closures)] |
a1dfa0c6 | 108 | #![feature(unsized_locals)] |
cc61c64b XL |
109 | #![feature(untagged_unions)] |
110 | #![feature(unwind_attributes)] | |
83c7162d | 111 | #![feature(doc_alias)] |
94b46f34 XL |
112 | #![feature(mmx_target_feature)] |
113 | #![feature(tbm_target_feature)] | |
114 | #![feature(sse4a_target_feature)] | |
115 | #![feature(arm_target_feature)] | |
116 | #![feature(powerpc_target_feature)] | |
117 | #![feature(mips_target_feature)] | |
118 | #![feature(aarch64_target_feature)] | |
0bf4aa26 | 119 | #![feature(wasm_target_feature)] |
0731742a | 120 | #![feature(avx512_target_feature)] |
9fa01778 | 121 | #![feature(cmpxchg16b_target_feature)] |
416331ca XL |
122 | #![feature(rtm_target_feature)] |
123 | #![feature(f16c_target_feature)] | |
124 | #![feature(hexagon_target_feature)] | |
b7449926 XL |
125 | #![feature(const_int_conversion)] |
126 | #![feature(const_transmute)] | |
a1dfa0c6 | 127 | #![feature(structural_match)] |
0731742a | 128 | #![feature(abi_unadjusted)] |
9fa01778 | 129 | #![feature(adx_target_feature)] |
e1599b0c | 130 | #![feature(maybe_uninit_slice)] |
9fa01778 | 131 | #![feature(external_doc)] |
416331ca | 132 | #![feature(associated_type_bounds)] |
ea8adc8c | 133 | |
9e0c209e SL |
134 | #[prelude_import] |
135 | #[allow(unused)] | |
136 | use prelude::v1::*; | |
5bcae85e | 137 | |
e74abb32 | 138 | #[cfg(not(test))] // See #65860 |
1a4d82fc JJ |
139 | #[macro_use] |
140 | mod macros; | |
141 | ||
c30ab7b3 SL |
142 | #[macro_use] |
143 | mod internal_macros; | |
144 | ||
1a4d82fc JJ |
145 | #[path = "num/int_macros.rs"] |
146 | #[macro_use] | |
147 | mod int_macros; | |
148 | ||
149 | #[path = "num/uint_macros.rs"] | |
150 | #[macro_use] | |
151 | mod uint_macros; | |
152 | ||
5bcae85e SL |
153 | #[path = "num/isize.rs"] pub mod isize; |
154 | #[path = "num/i8.rs"] pub mod i8; | |
155 | #[path = "num/i16.rs"] pub mod i16; | |
156 | #[path = "num/i32.rs"] pub mod i32; | |
157 | #[path = "num/i64.rs"] pub mod i64; | |
94b46f34 | 158 | #[path = "num/i128.rs"] pub mod i128; |
32a655c1 | 159 | |
1a4d82fc | 160 | #[path = "num/usize.rs"] pub mod usize; |
5bcae85e SL |
161 | #[path = "num/u8.rs"] pub mod u8; |
162 | #[path = "num/u16.rs"] pub mod u16; | |
163 | #[path = "num/u32.rs"] pub mod u32; | |
164 | #[path = "num/u64.rs"] pub mod u64; | |
94b46f34 | 165 | #[path = "num/u128.rs"] pub mod u128; |
32a655c1 | 166 | |
1a4d82fc JJ |
167 | #[path = "num/f32.rs"] pub mod f32; |
168 | #[path = "num/f64.rs"] pub mod f64; | |
169 | ||
9346a6ac | 170 | #[macro_use] |
1a4d82fc JJ |
171 | pub mod num; |
172 | ||
173 | /* The libcore prelude, not as all-encompassing as the libstd prelude */ | |
174 | ||
175 | pub mod prelude; | |
176 | ||
177 | /* Core modules for ownership management */ | |
178 | ||
179 | pub mod intrinsics; | |
180 | pub mod mem; | |
1a4d82fc | 181 | pub mod ptr; |
83c7162d | 182 | pub mod hint; |
1a4d82fc JJ |
183 | |
184 | /* Core language traits */ | |
185 | ||
e74abb32 | 186 | #[cfg(not(test))] // See #65860 |
1a4d82fc JJ |
187 | pub mod marker; |
188 | pub mod ops; | |
e74abb32 | 189 | #[cfg(not(test))] // See #65860 |
1a4d82fc | 190 | pub mod cmp; |
e74abb32 | 191 | #[cfg(not(test))] // See #65860 |
1a4d82fc | 192 | pub mod clone; |
e74abb32 | 193 | #[cfg(not(test))] // See #65860 |
1a4d82fc | 194 | pub mod default; |
c34b1796 | 195 | pub mod convert; |
e9174d1e | 196 | pub mod borrow; |
1a4d82fc JJ |
197 | |
198 | /* Core types and methods on primitives */ | |
199 | ||
200 | pub mod any; | |
e74abb32 | 201 | #[cfg(not(test))] // See #65860 |
c34b1796 | 202 | pub mod array; |
0531ce1d | 203 | pub mod ascii; |
e9174d1e | 204 | pub mod sync; |
1a4d82fc JJ |
205 | pub mod cell; |
206 | pub mod char; | |
0531ce1d | 207 | pub mod panic; |
1a4d82fc | 208 | pub mod panicking; |
e74abb32 | 209 | #[cfg(not(test))] // See #65860 |
b7449926 | 210 | pub mod pin; |
e74abb32 | 211 | #[cfg(not(test))] // See #65860 |
1a4d82fc JJ |
212 | pub mod iter; |
213 | pub mod option; | |
214 | pub mod raw; | |
215 | pub mod result; | |
b7449926 | 216 | pub mod ffi; |
e9174d1e | 217 | |
1a4d82fc | 218 | pub mod slice; |
e74abb32 | 219 | #[cfg(not(test))] // See #65860 |
1a4d82fc | 220 | pub mod str; |
e74abb32 | 221 | #[cfg(not(test))] // See #65860 |
1a4d82fc | 222 | pub mod hash; |
e74abb32 | 223 | #[cfg(not(test))] // See #65860 |
1a4d82fc | 224 | pub mod fmt; |
2c00a5a8 | 225 | pub mod time; |
85aaf69f | 226 | |
83c7162d XL |
227 | pub mod unicode; |
228 | ||
94b46f34 | 229 | /* Async */ |
e74abb32 | 230 | #[cfg(not(test))] // See #65860 |
94b46f34 XL |
231 | pub mod future; |
232 | pub mod task; | |
233 | ||
0531ce1d XL |
234 | /* Heap memory allocator trait */ |
235 | #[allow(missing_docs)] | |
83c7162d XL |
236 | pub mod alloc; |
237 | ||
1a4d82fc | 238 | // note: does not need to be public |
e1599b0c | 239 | mod bool; |
1a4d82fc | 240 | mod tuple; |
abe05a73 | 241 | mod unit; |
0531ce1d | 242 | |
9fa01778 | 243 | // Pull in the `core_arch` crate directly into libcore. The contents of |
416331ca | 244 | // `core_arch` are in a different repository: rust-lang/stdarch. |
9fa01778 XL |
245 | // |
246 | // `core_arch` depends on libcore, but the contents of this module are | |
247 | // set up in such a way that directly pulling it here works such that the | |
248 | // crate uses the this crate as its libcore. | |
416331ca | 249 | #[path = "../stdarch/crates/core_arch/src/mod.rs"] |
83c7162d | 250 | #[allow(missing_docs, missing_debug_implementations, dead_code, unused_imports)] |
0531ce1d | 251 | #[unstable(feature = "stdsimd", issue = "48556")] |
9fa01778 | 252 | mod core_arch; |
0531ce1d | 253 | |
83c7162d | 254 | #[stable(feature = "simd_arch", since = "1.27.0")] |
9fa01778 | 255 | pub use core_arch::arch; |