src/doc/book/no-stdlib.md

   1 % No stdlib
   2
   3 Rust’s standard library provides a lot of useful functionality, but assumes
   4 support for various features of its host system: threads, networking, heap
   5 allocation, and others. There are systems that do not have these features,
   6 however, and Rust can work with those too! To do so, we tell Rust that we
   7 don’t want to use the standard library via an attribute: `#![no_std]`.
   8
   9 > Note: This feature is technically stable, but there are some caveats. For
  10 > one, you can build a `#![no_std]` _library_ on stable, but not a _binary_.
  11 > For details on libraries without the standard library, see [the chapter on
  12 > `#![no_std]`](using-rust-without-the-standard-library.html)
  13
  14 Obviously there's more to life than just libraries: one can use
  15 `#[no_std]` with an executable.
  16
  17 ### Using libc
  18
  19 In order to build a `#[no_std]` executable we will need libc as a dependency. We can specify
  20 this using our `Cargo.toml` file:
  21
  22 ```toml
  23 [dependencies]
  24 libc = { version = "0.2.14", default-features = false }
  25 ```
  26
  27 Note that the default features have been disabled. This is a critical step -
  28 **the default features of libc include the standard library and so must be
  29 disabled.**
  30
  31 ### Writing an executable without stdlib
  32
  33 Controlling the entry point is possible in two ways: the `#[start]` attribute,
  34 or overriding the default shim for the C `main` function with your own.
  35
  36 The function marked `#[start]` is passed the command line parameters
  37 in the same format as C:
  38
  39 ```rust,ignore
  40 #![feature(lang_items)]
  41 #![feature(start)]
  42 #![no_std]
  43
  44 // Pull in the system libc library for what crt0.o likely requires
  45 extern crate libc;
  46
  47 // Entry point for this program
  48 #[start]
  49 fn start(_argc: isize, _argv: *const *const u8) -> isize {
  50     0
  51 }
  52
  53 // These functions are used by the compiler, but not
  54 // for a bare-bones hello world. These are normally
  55 // provided by libstd.
  56 #[lang = "eh_personality"]
  57 #[no_mangle]
  58 pub extern fn eh_personality() {
  59 }
  60
  61 #[lang = "panic_fmt"]
  62 #[no_mangle]
  63 pub extern fn rust_begin_panic(_msg: core::fmt::Arguments,
  64                                _file: &'static str,
  65                                _line: u32) -> ! {
  66     loop {}
  67 }
  68 ```
  69
  70 To override the compiler-inserted `main` shim, one has to disable it
  71 with `#![no_main]` and then create the appropriate symbol with the
  72 correct ABI and the correct name, which requires overriding the
  73 compiler's name mangling too:
  74
  75 ```rust,ignore
  76 #![feature(lang_items)]
  77 #![feature(start)]
  78 #![no_std]
  79 #![no_main]
  80
  81 // Pull in the system libc library for what crt0.o likely requires
  82 extern crate libc;
  83
  84 // Entry point for this program
  85 #[no_mangle] // ensure that this symbol is called `main` in the output
  86 pub extern fn main(_argc: i32, _argv: *const *const u8) -> i32 {
  87     0
  88 }
  89
  90 // These functions and traits are used by the compiler, but not
  91 // for a bare-bones hello world. These are normally
  92 // provided by libstd.
  93 #[lang = "eh_personality"]
  94 #[no_mangle]
  95 pub extern fn eh_personality() {
  96 }
  97
  98 #[lang = "panic_fmt"]
  99 #[no_mangle]
 100 pub extern fn rust_begin_panic(_msg: core::fmt::Arguments,
 101                                _file: &'static str,
 102                                _line: u32) -> ! {
 103     loop {}
 104 }
 105 ```
 106
 107 ## More about the langauge items
 108
 109 The compiler currently makes a few assumptions about symbols which are
 110 available in the executable to call. Normally these functions are provided by
 111 the standard library, but without it you must define your own. These symbols
 112 are called "language items", and they each have an internal name, and then a
 113 signature that an implementation must conform to.
 114
 115 The first of these two functions, `eh_personality`, is used by the failure
 116 mechanisms of the compiler. This is often mapped to GCC's personality function
 117 (see the [libstd implementation][unwind] for more information), but crates
 118 which do not trigger a panic can be assured that this function is never
 119 called. Both the language item and the symbol name are `eh_personality`.
 120
 121 [unwind]: https://github.com/rust-lang/rust/blob/master/src/libpanic_unwind/gcc.rs
 122
 123 The second function, `panic_fmt`, is also used by the failure mechanisms of the
 124 compiler. When a panic happens, this controls the message that's displayed on
 125 the screen. While the language item's name is `panic_fmt`, the symbol name is
 126 `rust_begin_panic`.