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, controlling the entry point is
  16 possible in two ways: the `#[start]` attribute, or overriding the
  17 default shim for the C `main` function with your own.
  18
  19 The function marked `#[start]` is passed the command line parameters
  20 in the same format as C:
  21
  22 ```rust
  23 # #![feature(libc)]
  24 #![feature(lang_items)]
  25 #![feature(start)]
  26 #![no_std]
  27
  28 // Pull in the system libc library for what crt0.o likely requires
  29 extern crate libc;
  30
  31 // Entry point for this program
  32 #[start]
  33 fn start(_argc: isize, _argv: *const *const u8) -> isize {
  34     0
  35 }
  36
  37 // These functions and traits are used by the compiler, but not
  38 // for a bare-bones hello world. These are normally
  39 // provided by libstd.
  40 #[lang = "eh_personality"] extern fn eh_personality() {}
  41 #[lang = "panic_fmt"] fn panic_fmt() -> ! { loop {} }
  42 # #[lang = "eh_unwind_resume"] extern fn rust_eh_unwind_resume() {}
  43 # #[no_mangle] pub extern fn rust_eh_register_frames () {}
  44 # #[no_mangle] pub extern fn rust_eh_unregister_frames () {}
  45 # // fn main() {} tricked you, rustdoc!
  46 ```
  47
  48 To override the compiler-inserted `main` shim, one has to disable it
  49 with `#![no_main]` and then create the appropriate symbol with the
  50 correct ABI and the correct name, which requires overriding the
  51 compiler's name mangling too:
  52
  53 ```rust
  54 # #![feature(libc)]
  55 #![feature(lang_items)]
  56 #![feature(start)]
  57 #![no_std]
  58 #![no_main]
  59
  60 extern crate libc;
  61
  62 #[no_mangle] // ensure that this symbol is called `main` in the output
  63 pub extern fn main(argc: i32, argv: *const *const u8) -> i32 {
  64     0
  65 }
  66
  67 #[lang = "eh_personality"] extern fn eh_personality() {}
  68 #[lang = "panic_fmt"] fn panic_fmt() -> ! { loop {} }
  69 # #[lang = "eh_unwind_resume"] extern fn rust_eh_unwind_resume() {}
  70 # #[no_mangle] pub extern fn rust_eh_register_frames () {}
  71 # #[no_mangle] pub extern fn rust_eh_unregister_frames () {}
  72 # // fn main() {} tricked you, rustdoc!
  73 ```
  74
  75
  76 The compiler currently makes a few assumptions about symbols which are available
  77 in the executable to call. Normally these functions are provided by the standard
  78 library, but without it you must define your own.
  79
  80 The first of these two functions, `eh_personality`, is used by the
  81 failure mechanisms of the compiler. This is often mapped to GCC's
  82 personality function (see the
  83 [libstd implementation](../std/rt/unwind/index.html) for more
  84 information), but crates which do not trigger a panic can be assured
  85 that this function is never called. The second function, `panic_fmt`, is
  86 also used by the failure mechanisms of the compiler.