diff options
| -rw-r--r-- | src/doc/book/no-stdlib.md | 73 | ||||
| -rw-r--r-- | 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. |