]>
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, | |
dfeec247 | 47 | // and this will cause the E0152 "found duplicate lang item" error. See |
83c7162d XL |
48 | // discussion in #50466 for details. |
49 | // | |
50 | // This cfg won't affect doc tests. | |
51 | #![cfg(not(test))] | |
92a42be0 | 52 | #![stable(feature = "core", since = "1.6.0")] |
dfeec247 XL |
53 | #![doc( |
54 | html_root_url = "https://doc.rust-lang.org/nightly/", | |
55 | html_playground_url = "https://play.rust-lang.org/", | |
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))) | |
59 | )] | |
e9174d1e | 60 | #![no_core] |
9fa01778 XL |
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)] |
e9174d1e | 67 | #![feature(allow_internal_unstable)] |
94b46f34 | 68 | #![feature(arbitrary_self_types)] |
a7813a04 | 69 | #![feature(asm)] |
dc9dc135 | 70 | #![feature(bound_cloned)] |
cc61c64b | 71 | #![feature(cfg_target_has_atomic)] |
e9174d1e | 72 | #![feature(concat_idents)] |
74b04a01 | 73 | #![feature(const_ascii_ctype_on_intrinsics)] |
dfeec247 | 74 | #![feature(const_alloc_layout)] |
ba9703b0 | 75 | #![feature(const_discriminant)] |
f035d41b XL |
76 | #![cfg_attr(bootstrap, feature(const_if_match))] |
77 | #![cfg_attr(bootstrap, feature(const_loop))] | |
74b04a01 XL |
78 | #![feature(const_checked_int_methods)] |
79 | #![feature(const_euclidean_int_methods)] | |
80 | #![feature(const_overflowing_int_methods)] | |
81 | #![feature(const_saturating_int_methods)] | |
82 | #![feature(const_int_unchecked_arith)] | |
83 | #![feature(const_int_pow)] | |
84 | #![feature(constctlz)] | |
dfeec247 | 85 | #![feature(const_panic)] |
b7449926 | 86 | #![feature(const_fn_union)] |
416331ca | 87 | #![feature(const_generics)] |
f9f354fc | 88 | #![feature(const_ptr_offset)] |
dfeec247 | 89 | #![feature(const_ptr_offset_from)] |
f035d41b | 90 | #![cfg_attr(not(bootstrap), feature(const_raw_ptr_comparison))] |
dfeec247 | 91 | #![feature(const_result)] |
f9f354fc XL |
92 | #![feature(const_slice_from_raw_parts)] |
93 | #![feature(const_slice_ptr_len)] | |
dfeec247 | 94 | #![feature(const_type_name)] |
f035d41b | 95 | #![feature(const_likely)] |
416331ca XL |
96 | #![feature(custom_inner_attributes)] |
97 | #![feature(decl_macro)] | |
0531ce1d | 98 | #![feature(doc_cfg)] |
83c7162d | 99 | #![feature(extern_types)] |
e9174d1e | 100 | #![feature(fundamental)] |
62682a34 | 101 | #![feature(intrinsics)] |
dfeec247 | 102 | #![feature(try_find)] |
9fa01778 | 103 | #![feature(is_sorted)] |
62682a34 | 104 | #![feature(lang_items)] |
0531ce1d | 105 | #![feature(link_llvm_intrinsics)] |
ba9703b0 | 106 | #![feature(llvm_asm)] |
f9f354fc | 107 | #![feature(negative_impls)] |
cc61c64b | 108 | #![feature(never_type)] |
0bf4aa26 | 109 | #![feature(nll)] |
0531ce1d | 110 | #![feature(exhaustive_patterns)] |
e9174d1e | 111 | #![feature(no_core)] |
c34b1796 | 112 | #![feature(optin_builtin_traits)] |
ba9703b0 | 113 | #![feature(or_patterns)] |
cc61c64b | 114 | #![feature(prelude_import)] |
9cc50fc6 | 115 | #![feature(repr_simd, platform_intrinsics)] |
54a0048b | 116 | #![feature(rustc_attrs)] |
0531ce1d | 117 | #![feature(simd_ffi)] |
54a0048b | 118 | #![feature(specialization)] |
e9174d1e | 119 | #![feature(staged_api)] |
9fa01778 | 120 | #![feature(std_internals)] |
0531ce1d | 121 | #![feature(stmt_expr_attributes)] |
f035d41b | 122 | #![cfg_attr(bootstrap, feature(track_caller))] |
416331ca | 123 | #![feature(transparent_unions)] |
e9174d1e | 124 | #![feature(unboxed_closures)] |
a1dfa0c6 | 125 | #![feature(unsized_locals)] |
cc61c64b XL |
126 | #![feature(untagged_unions)] |
127 | #![feature(unwind_attributes)] | |
f035d41b | 128 | #![cfg_attr(not(bootstrap), feature(variant_count))] |
83c7162d | 129 | #![feature(doc_alias)] |
94b46f34 XL |
130 | #![feature(mmx_target_feature)] |
131 | #![feature(tbm_target_feature)] | |
132 | #![feature(sse4a_target_feature)] | |
133 | #![feature(arm_target_feature)] | |
134 | #![feature(powerpc_target_feature)] | |
135 | #![feature(mips_target_feature)] | |
136 | #![feature(aarch64_target_feature)] | |
0bf4aa26 | 137 | #![feature(wasm_target_feature)] |
0731742a | 138 | #![feature(avx512_target_feature)] |
9fa01778 | 139 | #![feature(cmpxchg16b_target_feature)] |
416331ca XL |
140 | #![feature(rtm_target_feature)] |
141 | #![feature(f16c_target_feature)] | |
142 | #![feature(hexagon_target_feature)] | |
f035d41b | 143 | #![cfg_attr(not(bootstrap), feature(const_fn_transmute))] |
0731742a | 144 | #![feature(abi_unadjusted)] |
9fa01778 | 145 | #![feature(adx_target_feature)] |
e1599b0c | 146 | #![feature(maybe_uninit_slice)] |
9fa01778 | 147 | #![feature(external_doc)] |
416331ca | 148 | #![feature(associated_type_bounds)] |
dfeec247 XL |
149 | #![feature(const_type_id)] |
150 | #![feature(const_caller_location)] | |
ba9703b0 | 151 | #![feature(no_niche)] // rust-lang/rust#68303 |
f035d41b XL |
152 | #![feature(unsafe_block_in_unsafe_fn)] |
153 | #![deny(unsafe_op_in_unsafe_fn)] | |
ea8adc8c | 154 | |
9e0c209e SL |
155 | #[prelude_import] |
156 | #[allow(unused)] | |
157 | use prelude::v1::*; | |
5bcae85e | 158 | |
e74abb32 | 159 | #[cfg(not(test))] // See #65860 |
1a4d82fc JJ |
160 | #[macro_use] |
161 | mod macros; | |
162 | ||
c30ab7b3 SL |
163 | #[macro_use] |
164 | mod internal_macros; | |
165 | ||
1a4d82fc JJ |
166 | #[path = "num/int_macros.rs"] |
167 | #[macro_use] | |
168 | mod int_macros; | |
169 | ||
dfeec247 XL |
170 | #[path = "num/i128.rs"] |
171 | pub mod i128; | |
172 | #[path = "num/i16.rs"] | |
173 | pub mod i16; | |
174 | #[path = "num/i32.rs"] | |
175 | pub mod i32; | |
176 | #[path = "num/i64.rs"] | |
177 | pub mod i64; | |
178 | #[path = "num/i8.rs"] | |
179 | pub mod i8; | |
180 | #[path = "num/isize.rs"] | |
181 | pub mod isize; | |
32a655c1 | 182 | |
dfeec247 XL |
183 | #[path = "num/u128.rs"] |
184 | pub mod u128; | |
185 | #[path = "num/u16.rs"] | |
186 | pub mod u16; | |
187 | #[path = "num/u32.rs"] | |
188 | pub mod u32; | |
189 | #[path = "num/u64.rs"] | |
190 | pub mod u64; | |
191 | #[path = "num/u8.rs"] | |
192 | pub mod u8; | |
193 | #[path = "num/usize.rs"] | |
194 | pub mod usize; | |
32a655c1 | 195 | |
dfeec247 XL |
196 | #[path = "num/f32.rs"] |
197 | pub mod f32; | |
198 | #[path = "num/f64.rs"] | |
199 | pub mod f64; | |
1a4d82fc | 200 | |
9346a6ac | 201 | #[macro_use] |
1a4d82fc JJ |
202 | pub mod num; |
203 | ||
204 | /* The libcore prelude, not as all-encompassing as the libstd prelude */ | |
205 | ||
206 | pub mod prelude; | |
207 | ||
208 | /* Core modules for ownership management */ | |
209 | ||
dfeec247 | 210 | pub mod hint; |
1a4d82fc JJ |
211 | pub mod intrinsics; |
212 | pub mod mem; | |
1a4d82fc JJ |
213 | pub mod ptr; |
214 | ||
215 | /* Core language traits */ | |
216 | ||
dfeec247 | 217 | pub mod borrow; |
e74abb32 | 218 | #[cfg(not(test))] // See #65860 |
dfeec247 | 219 | pub mod clone; |
e74abb32 | 220 | #[cfg(not(test))] // See #65860 |
1a4d82fc | 221 | pub mod cmp; |
dfeec247 | 222 | pub mod convert; |
e74abb32 | 223 | #[cfg(not(test))] // See #65860 |
1a4d82fc | 224 | pub mod default; |
dfeec247 XL |
225 | #[cfg(not(test))] // See #65860 |
226 | pub mod marker; | |
227 | pub mod ops; | |
1a4d82fc JJ |
228 | |
229 | /* Core types and methods on primitives */ | |
230 | ||
231 | pub mod any; | |
e74abb32 | 232 | #[cfg(not(test))] // See #65860 |
c34b1796 | 233 | pub mod array; |
0531ce1d | 234 | pub mod ascii; |
1a4d82fc JJ |
235 | pub mod cell; |
236 | pub mod char; | |
dfeec247 XL |
237 | pub mod ffi; |
238 | #[cfg(not(test))] // See #65860 | |
239 | pub mod iter; | |
240 | pub mod option; | |
0531ce1d | 241 | pub mod panic; |
1a4d82fc | 242 | pub mod panicking; |
e74abb32 | 243 | #[cfg(not(test))] // See #65860 |
b7449926 | 244 | pub mod pin; |
1a4d82fc JJ |
245 | pub mod raw; |
246 | pub mod result; | |
dfeec247 | 247 | pub mod sync; |
e9174d1e | 248 | |
e74abb32 | 249 | #[cfg(not(test))] // See #65860 |
dfeec247 | 250 | pub mod fmt; |
e74abb32 | 251 | #[cfg(not(test))] // See #65860 |
1a4d82fc | 252 | pub mod hash; |
dfeec247 | 253 | pub mod slice; |
e74abb32 | 254 | #[cfg(not(test))] // See #65860 |
dfeec247 | 255 | pub mod str; |
2c00a5a8 | 256 | pub mod time; |
85aaf69f | 257 | |
83c7162d XL |
258 | pub mod unicode; |
259 | ||
94b46f34 | 260 | /* Async */ |
e74abb32 | 261 | #[cfg(not(test))] // See #65860 |
94b46f34 XL |
262 | pub mod future; |
263 | pub mod task; | |
264 | ||
0531ce1d XL |
265 | /* Heap memory allocator trait */ |
266 | #[allow(missing_docs)] | |
83c7162d XL |
267 | pub mod alloc; |
268 | ||
1a4d82fc | 269 | // note: does not need to be public |
e1599b0c | 270 | mod bool; |
1a4d82fc | 271 | mod tuple; |
abe05a73 | 272 | mod unit; |
0531ce1d | 273 | |
74b04a01 XL |
274 | #[stable(feature = "core_primitive", since = "1.43.0")] |
275 | pub mod primitive; | |
276 | ||
9fa01778 | 277 | // Pull in the `core_arch` crate directly into libcore. The contents of |
416331ca | 278 | // `core_arch` are in a different repository: rust-lang/stdarch. |
9fa01778 XL |
279 | // |
280 | // `core_arch` depends on libcore, but the contents of this module are | |
281 | // set up in such a way that directly pulling it here works such that the | |
282 | // crate uses the this crate as its libcore. | |
416331ca | 283 | #[path = "../stdarch/crates/core_arch/src/mod.rs"] |
f035d41b XL |
284 | #[allow( |
285 | missing_docs, | |
286 | missing_debug_implementations, | |
287 | dead_code, | |
288 | unused_imports, | |
289 | unsafe_op_in_unsafe_fn | |
290 | )] | |
291 | // FIXME: This annotation should be moved into rust-lang/stdarch after clashing_extern_declarations is | |
292 | // merged. It currently cannot because bootstrap fails as the lint hasn't been defined yet. | |
293 | #[cfg_attr(not(bootstrap), allow(clashing_extern_declarations))] | |
0531ce1d | 294 | #[unstable(feature = "stdsimd", issue = "48556")] |
9fa01778 | 295 | mod core_arch; |
0531ce1d | 296 | |
83c7162d | 297 | #[stable(feature = "simd_arch", since = "1.27.0")] |
9fa01778 | 298 | pub use core_arch::arch; |