diff --git a/src/doc/book/no-stdlib.md b/src/doc/book/no-stdlib.md index c5c139e6580b0..6fd7cf66920d4 100644 --- a/src/doc/book/no-stdlib.md +++ b/src/doc/book/no-stdlib.md @@ -21,7 +21,7 @@ this using our `Cargo.toml` file: ```toml [dependencies] -libc = { version = "0.2.11", default-features = false } +libc = { version = "0.2.14", default-features = false } ``` Note that the default features have been disabled. This is a critical step - @@ -36,8 +36,7 @@ or overriding the default shim for the C `main` function with your own. The function marked `#[start]` is passed the command line parameters in the same format as C: -```rust -# #![feature(libc)] +```rust,ignore #![feature(lang_items)] #![feature(start)] #![no_std] @@ -51,15 +50,21 @@ fn start(_argc: isize, _argv: *const *const u8) -> isize { 0 } -// These functions and traits are used by the compiler, but not +// These functions are used by the compiler, but not // for a bare-bones hello world. These are normally // provided by libstd. -#[lang = "eh_personality"] extern fn eh_personality() {} -#[lang = "panic_fmt"] extern fn panic_fmt() -> ! { loop {} } -# #[lang = "eh_unwind_resume"] extern fn rust_eh_unwind_resume() {} -# #[no_mangle] pub extern fn rust_eh_register_frames () {} -# #[no_mangle] pub extern fn rust_eh_unregister_frames () {} -# // fn main() {} tricked you, rustdoc! +#[lang = "eh_personality"] +#[no_mangle] +pub extern fn eh_personality() { +} + +#[lang = "panic_fmt"] +#[no_mangle] +pub extern fn rust_begin_panic(_msg: core::fmt::Arguments, + _file: &'static str, + _line: u32) -> ! { + loop {} +} ``` To override the compiler-inserted `main` shim, one has to disable it @@ -67,37 +72,55 @@ with `#![no_main]` and then create the appropriate symbol with the correct ABI and the correct name, which requires overriding the compiler's name mangling too: -```rust -# #![feature(libc)] +```rust,ignore #![feature(lang_items)] #![feature(start)] #![no_std] #![no_main] +// Pull in the system libc library for what crt0.o likely requires extern crate libc; +// Entry point for this program #[no_mangle] // ensure that this symbol is called `main` in the output -pub extern fn main(argc: i32, argv: *const *const u8) -> i32 { +pub extern fn main(_argc: i32, _argv: *const *const u8) -> i32 { 0 } -#[lang = "eh_personality"] extern fn eh_personality() {} -#[lang = "panic_fmt"] extern fn panic_fmt() -> ! { loop {} } -# #[lang = "eh_unwind_resume"] extern fn rust_eh_unwind_resume() {} -# #[no_mangle] pub extern fn rust_eh_register_frames () {} -# #[no_mangle] pub extern fn rust_eh_unregister_frames () {} -# // fn main() {} tricked you, rustdoc! +// These functions and traits are used by the compiler, but not +// for a bare-bones hello world. These are normally +// provided by libstd. +#[lang = "eh_personality"] +#[no_mangle] +pub extern fn eh_personality() { +} + +#[lang = "panic_fmt"] +#[no_mangle] +pub extern fn rust_begin_panic(_msg: core::fmt::Arguments, + _file: &'static str, + _line: u32) -> ! { + loop {} +} ``` -The compiler currently makes a few assumptions about symbols which are available -in the executable to call. Normally these functions are provided by the standard -library, but without it you must define your own. +## More about the langauge items + +The compiler currently makes a few assumptions about symbols which are +available in the executable to call. Normally these functions are provided by +the standard library, but without it you must define your own. These symbols +are called "language items", and they each have an internal name, and then a +signature that an implementation must conform to. The first of these two functions, `eh_personality`, is used by the failure mechanisms of the compiler. This is often mapped to GCC's personality function (see the [libstd implementation][unwind] for more information), but crates which do not trigger a panic can be assured that this function is never -called. The second function, `panic_fmt`, is also used by the failure -mechanisms of the compiler. - +called. Both the language item and the symbol name are `eh_personality`. + [unwind]: https://github.com/rust-lang/rust/blob/master/src/libpanic_unwind/gcc.rs + +The second function, `panic_fmt`, is also used by the failure mechanisms of the +compiler. When a panic happens, this controls the message that's displayed on +the screen. While the language item's name is `panic_fmt`, the symbol name is +`rust_begin_panic`. diff --git a/src/doc/nomicon/phantom-data.md b/src/doc/nomicon/phantom-data.md index 0d7ec7f161796..d565532017a65 100644 --- a/src/doc/nomicon/phantom-data.md +++ b/src/doc/nomicon/phantom-data.md @@ -51,12 +51,12 @@ struct Vec { ``` Unlike the previous example it *appears* that everything is exactly as we -want. Every generic argument to Vec shows up in the at least one field. +want. Every generic argument to Vec shows up in at least one field. Good to go! Nope. -The drop checker will generously determine that Vec does not own any values +The drop checker will generously determine that `Vec` does not own any values of type T. This will in turn make it conclude that it doesn't need to worry about Vec dropping any T's in its destructor for determining drop check soundness. This will in turn allow people to create unsoundness using @@ -81,7 +81,7 @@ Raw pointers that own an allocation is such a pervasive pattern that the standard library made a utility for itself called `Unique` which: * wraps a `*const T` for variance -* includes a `PhantomData`, +* includes a `PhantomData` * auto-derives Send/Sync as if T was contained * marks the pointer as NonZero for the null-pointer optimization diff --git a/src/doc/reference.md b/src/doc/reference.md index b3073f5e52603..b8509321e3d19 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -853,6 +853,20 @@ extern crate std; // equivalent to: extern crate std as std; extern crate std as ruststd; // linking to 'std' under another name ``` +When naming Rust crates, hyphens are disallowed. However, Cargo packages may +make use of them. In such case, when `Cargo.toml` doesn't specify a crate name, +Cargo will transparently replace `-` with `_` (Refer to [RFC 940] for more +details). + +Here is an example: + +```{.ignore} +// Importing the Cargo package hello-world +extern crate hello_world; // hyphen replaced with an underscore +``` + +[RFC 940]: https://github.com/rust-lang/rfcs/blob/master/text/0940-hyphens-considered-harmful.md + #### Use declarations A _use declaration_ creates one or more local name bindings synonymous with @@ -3744,9 +3758,9 @@ Since `'static` "lives longer" than `'a`, `&'static str` is a subtype of ## Type coercions -Coercions are defined in [RFC401]. A coercion is implicit and has no syntax. +Coercions are defined in [RFC 401]. A coercion is implicit and has no syntax. -[RFC401]: https://github.com/rust-lang/rfcs/blob/master/text/0401-coercions.md +[RFC 401]: https://github.com/rust-lang/rfcs/blob/master/text/0401-coercions.md ### Coercion sites @@ -3886,7 +3900,7 @@ Coercion is allowed between the following types: In the future, coerce_inner will be recursively extended to tuples and structs. In addition, coercions from sub-traits to super-traits will be - added. See [RFC401] for more details. + added. See [RFC 401] for more details. # Special traits diff --git a/src/libcore/hash/sip.rs b/src/libcore/hash/sip.rs index c52c0b0730be7..4a806a3c98602 100644 --- a/src/libcore/hash/sip.rs +++ b/src/libcore/hash/sip.rs @@ -18,7 +18,7 @@ use ptr; /// An implementation of SipHash 1-3. /// /// See: https://131002.net/siphash/ -#[unstable(feature = "sip_hash_13", issue = "29754")] +#[unstable(feature = "sip_hash_13", issue = "34767")] #[derive(Debug, Clone, Default)] pub struct SipHasher13 { hasher: Hasher, @@ -27,7 +27,7 @@ pub struct SipHasher13 { /// An implementation of SipHash 2-4. /// /// See: https://131002.net/siphash/ -#[unstable(feature = "sip_hash_13", issue = "29754")] +#[unstable(feature = "sip_hash_13", issue = "34767")] #[derive(Debug, Clone, Default)] pub struct SipHasher24 { hasher: Hasher, @@ -154,14 +154,14 @@ impl SipHasher { impl SipHasher13 { /// Creates a new `SipHasher13` with the two initial keys set to 0. #[inline] - #[unstable(feature = "sip_hash_13", issue = "29754")] + #[unstable(feature = "sip_hash_13", issue = "34767")] pub fn new() -> SipHasher13 { SipHasher13::new_with_keys(0, 0) } /// Creates a `SipHasher13` that is keyed off the provided keys. #[inline] - #[unstable(feature = "sip_hash_13", issue = "29754")] + #[unstable(feature = "sip_hash_13", issue = "34767")] pub fn new_with_keys(key0: u64, key1: u64) -> SipHasher13 { SipHasher13 { hasher: Hasher::new_with_keys(key0, key1) @@ -172,14 +172,14 @@ impl SipHasher13 { impl SipHasher24 { /// Creates a new `SipHasher24` with the two initial keys set to 0. #[inline] - #[unstable(feature = "sip_hash_13", issue = "29754")] + #[unstable(feature = "sip_hash_13", issue = "34767")] pub fn new() -> SipHasher24 { SipHasher24::new_with_keys(0, 0) } /// Creates a `SipHasher24` that is keyed off the provided keys. #[inline] - #[unstable(feature = "sip_hash_13", issue = "29754")] + #[unstable(feature = "sip_hash_13", issue = "34767")] pub fn new_with_keys(key0: u64, key1: u64) -> SipHasher24 { SipHasher24 { hasher: Hasher::new_with_keys(key0, key1) @@ -232,7 +232,7 @@ impl super::Hasher for SipHasher { } } -#[unstable(feature = "sip_hash_13", issue = "29754")] +#[unstable(feature = "sip_hash_13", issue = "34767")] impl super::Hasher for SipHasher13 { #[inline] fn write(&mut self, msg: &[u8]) { @@ -245,7 +245,7 @@ impl super::Hasher for SipHasher13 { } } -#[unstable(feature = "sip_hash_13", issue = "29754")] +#[unstable(feature = "sip_hash_13", issue = "34767")] impl super::Hasher for SipHasher24 { #[inline] fn write(&mut self, msg: &[u8]) { diff --git a/src/libcore/lib.rs b/src/libcore/lib.rs index e849369d647c4..0ad1f671f155b 100644 --- a/src/libcore/lib.rs +++ b/src/libcore/lib.rs @@ -25,6 +25,8 @@ //! //! # How to use the core library //! +//! Please note that all of these details are currently not considered stable. +//! // FIXME: Fill me in with more detail when the interface settles //! This library is built on the assumption of a few existing symbols: //! @@ -34,11 +36,12 @@ //! These functions are often provided by the system libc, but can also be //! provided by the [rlibc crate](https://crates.io/crates/rlibc). //! -//! * `rust_begin_unwind` - This function takes three arguments, a -//! `fmt::Arguments`, a `&str`, and a `u32`. These three arguments dictate -//! the panic message, the file at which panic was invoked, and the line. -//! It is up to consumers of this core library to define this panic -//! function; it is only required to never return. +//! * `rust_begin_panic` - This function takes three arguments, a +//! `fmt::Arguments`, a `&'static str`, and a `u32`. These three arguments +//! dictate the panic message, the file at which panic was invoked, and the +//! line. It is up to consumers of this core library to define this panic +//! function; it is only required to never return. This requires a `lang` +//! attribute named `panic_fmt`. // Since libcore defines many fundamental lang items, all tests live in a // separate crate, libcoretest, to avoid bizarre issues. diff --git a/src/libcore/num/mod.rs b/src/libcore/num/mod.rs index fcdbde0d19f4f..97648cc34699a 100644 --- a/src/libcore/num/mod.rs +++ b/src/libcore/num/mod.rs @@ -2318,7 +2318,7 @@ impl usize { /// let num = 12.4_f32; /// let inf = f32::INFINITY; /// let zero = 0f32; -/// let sub: f32 = 0.000000000000000000000000000000000000011754942; +/// let sub: f32 = 1.1754942e-38; /// let nan = f32::NAN; /// /// assert_eq!(num.classify(), FpCategory::Normal);