From 8f76f931c243dce31e2121a265ab0501b19504d5 Mon Sep 17 00:00:00 2001 From: Isaac Andrade Date: Mon, 2 May 2016 16:15:46 -0700 Subject: [PATCH 1/8] Add mention to RFC 940 in the Rust Reference. - It also keeps mentions to RFCs consistent with the format "RFC XXX" --- src/doc/reference.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/src/doc/reference.md b/src/doc/reference.md index fcf9aefaba8..87eede0b737 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -845,6 +845,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; // The crate name replaced the hyphen +``` + +[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 @@ -3720,9 +3734,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 @@ -3862,7 +3876,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 From ba6ce123bac969ee896a776699a8fad651a0a1cd Mon Sep 17 00:00:00 2001 From: Isaac Andrade Date: Tue, 3 May 2016 08:29:44 -0700 Subject: [PATCH 2/8] Improve language. --- src/doc/reference.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/doc/reference.md b/src/doc/reference.md index 87eede0b737..862e57d0160 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -846,15 +846,15 @@ 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, +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; // The crate name replaced the hyphen +// 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 From 767e14983e8b93fe111fb53fe802b4e7753ffbe6 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Mon, 11 Jul 2016 13:09:44 -0700 Subject: [PATCH 3/8] std: Correct tracking issue for SipHash{13,24} The referenced tracking issue was closed and was actually about changing the algorithm. cc #34767 --- src/libcore/hash/sip.rs | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/libcore/hash/sip.rs b/src/libcore/hash/sip.rs index c52c0b0730b..4a806a3c986 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]) { From b10ac8a4501201d3209129906757b107ad6357f8 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Fri, 15 Jul 2016 17:51:27 +0200 Subject: [PATCH 4/8] Improve float number example --- src/libcore/num/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcore/num/mod.rs b/src/libcore/num/mod.rs index fcdbde0d19f..97648cc3469 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); From fcecdac96d718b90849f210e1ccd6be45dc6ff1e Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Fri, 15 Jul 2016 13:17:35 -0400 Subject: [PATCH 5/8] Fix up documentation around no_std 1. Fix the sections in the book to have the correct signatures. I've also marked them as `ignore`; there's no way to set the `no_std` feature for libc, so it pulls in the stdlib, so this wasn't even testing the actual thing it was testing. Better to just ignore. 2. Correcting libcore's docs for factual inaccuracy, and add a note about language items. Fixes #33677 --- src/doc/book/no-stdlib.md | 73 +++++++++++++++++++++++++-------------- src/libcore/lib.rs | 13 ++++--- 2 files changed, 56 insertions(+), 30 deletions(-) diff --git a/src/doc/book/no-stdlib.md b/src/doc/book/no-stdlib.md index c5c139e6580..6fd7cf66920 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/libcore/lib.rs b/src/libcore/lib.rs index e849369d647..0ad1f671f15 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. From fc0d037265beee18458b671cd46a7a9a53706a16 Mon Sep 17 00:00:00 2001 From: Bastien Dejean Date: Sat, 16 Jul 2016 10:50:19 +0200 Subject: [PATCH 6/8] Add missing inline code delimiters around Vec --- src/doc/nomicon/phantom-data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/nomicon/phantom-data.md b/src/doc/nomicon/phantom-data.md index 0d7ec7f1617..2be14c15016 100644 --- a/src/doc/nomicon/phantom-data.md +++ b/src/doc/nomicon/phantom-data.md @@ -56,7 +56,7 @@ 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 From cc2176d3fea15b5a67acc959ca92e0ee6521515c Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Jul 2016 11:10:05 +0200 Subject: [PATCH 7/8] doc: remove stray comma --- src/doc/nomicon/phantom-data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/nomicon/phantom-data.md b/src/doc/nomicon/phantom-data.md index 0d7ec7f1617..ba9ef19830b 100644 --- a/src/doc/nomicon/phantom-data.md +++ b/src/doc/nomicon/phantom-data.md @@ -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 From 29ca456dfce27667341f4f26eec2b4efd13ffa17 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Jul 2016 11:13:29 +0200 Subject: [PATCH 8/8] doc: remove extraneous word --- src/doc/nomicon/phantom-data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/nomicon/phantom-data.md b/src/doc/nomicon/phantom-data.md index 0d7ec7f1617..4843cd420df 100644 --- a/src/doc/nomicon/phantom-data.md +++ b/src/doc/nomicon/phantom-data.md @@ -51,7 +51,7 @@ 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.