Rollup merge of rust-lang#34838 - steveklabnik:gh33677, r=alexcrichton

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 rust-lang#33677

r? @alexcrichton

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,53 +50,77 @@ 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
 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`.

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.