src/doc/book/no-stdlib.md

   1 % No stdlib
   2
   3 By default, `std` is linked to every Rust crate. In some contexts,
   4 this is undesirable, and can be avoided with the `#![no_std]`
   5 attribute attached to the crate.
   6
   7 Obviously there's more to life than just libraries: one can use
   8 `#[no_std]` with an executable, controlling the entry point is
   9 possible in two ways: the `#[start]` attribute, or overriding the
  10 default shim for the C `main` function with your own.
  11
  12 The function marked `#[start]` is passed the command line parameters
  13 in the same format as C:
  14
  15 ```rust
  16 # #![feature(libc)]
  17 #![feature(lang_items)]
  18 #![feature(start)]
  19 #![no_std]
  20
  21 // Pull in the system libc library for what crt0.o likely requires
  22 extern crate libc;
  23
  24 // Entry point for this program
  25 #[start]
  26 fn start(_argc: isize, _argv: *const *const u8) -> isize {
  27     0
  28 }
  29
  30 // These functions and traits are used by the compiler, but not
  31 // for a bare-bones hello world. These are normally
  32 // provided by libstd.
  33 #[lang = "eh_personality"] extern fn eh_personality() {}
  34 #[lang = "panic_fmt"] fn panic_fmt() -> ! { loop {} }
  35 # #[lang = "eh_unwind_resume"] extern fn rust_eh_unwind_resume() {}
  36 # #[no_mangle] pub extern fn rust_eh_register_frames () {}
  37 # #[no_mangle] pub extern fn rust_eh_unregister_frames () {}
  38 # // fn main() {} tricked you, rustdoc!
  39 ```
  40
  41 To override the compiler-inserted `main` shim, one has to disable it
  42 with `#![no_main]` and then create the appropriate symbol with the
  43 correct ABI and the correct name, which requires overriding the
  44 compiler's name mangling too:
  45
  46 ```rust
  47 # #![feature(libc)]
  48 #![feature(lang_items)]
  49 #![feature(start)]
  50 #![no_std]
  51 #![no_main]
  52
  53 extern crate libc;
  54
  55 #[no_mangle] // ensure that this symbol is called `main` in the output
  56 pub extern fn main(argc: i32, argv: *const *const u8) -> i32 {
  57     0
  58 }
  59
  60 #[lang = "eh_personality"] extern fn eh_personality() {}
  61 #[lang = "panic_fmt"] fn panic_fmt() -> ! { loop {} }
  62 # #[lang = "eh_unwind_resume"] extern fn rust_eh_unwind_resume() {}
  63 # #[no_mangle] pub extern fn rust_eh_register_frames () {}
  64 # #[no_mangle] pub extern fn rust_eh_unregister_frames () {}
  65 # // fn main() {} tricked you, rustdoc!
  66 ```
  67
  68
  69 The compiler currently makes a few assumptions about symbols which are available
  70 in the executable to call. Normally these functions are provided by the standard
  71 library, but without it you must define your own.
  72
  73 The first of these two functions, `eh_personality`, is used by the
  74 failure mechanisms of the compiler. This is often mapped to GCC's
  75 personality function (see the
  76 [libstd implementation](../std/rt/unwind/index.html) for more
  77 information), but crates which do not trigger a panic can be assured
  78 that this function is never called. The second function, `panic_fmt`, is
  79 also used by the failure mechanisms of the compiler.
  80
  81 ## Using libcore
  82
  83 > **Note**: the core library's structure is unstable, and it is recommended to
  84 > use the standard library instead wherever possible.
  85
  86 With the above techniques, we've got a bare-metal executable running some Rust
  87 code. There is a good deal of functionality provided by the standard library,
  88 however, that is necessary to be productive in Rust. If the standard library is
  89 not sufficient, then [libcore](../core/index.html) is designed to be used
  90 instead.
  91
  92 The core library has very few dependencies and is much more portable than the
  93 standard library itself. Additionally, the core library has most of the
  94 necessary functionality for writing idiomatic and effective Rust code. When
  95 using `#![no_std]`, Rust will automatically inject the `core` crate, like
  96 we do for `std` when we’re using it.
  97
  98 As an example, here is a program that will calculate the dot product of two
  99 vectors provided from C, using idiomatic Rust practices.
 100
 101 ```rust
 102 # #![feature(libc)]
 103 #![feature(lang_items)]
 104 #![feature(start)]
 105 #![feature(raw)]
 106 #![no_std]
 107
 108 extern crate libc;
 109
 110 use core::mem;
 111
 112 #[no_mangle]
 113 pub extern fn dot_product(a: *const u32, a_len: u32,
 114                           b: *const u32, b_len: u32) -> u32 {
 115     use core::raw::Slice;
 116
 117     // Convert the provided arrays into Rust slices.
 118     // The core::raw module guarantees that the Slice
 119     // structure has the same memory layout as a &[T]
 120     // slice.
 121     //
 122     // This is an unsafe operation because the compiler
 123     // cannot tell the pointers are valid.
 124     let (a_slice, b_slice): (&[u32], &[u32]) = unsafe {
 125         mem::transmute((
 126             Slice { data: a, len: a_len as usize },
 127             Slice { data: b, len: b_len as usize },
 128         ))
 129     };
 130
 131     // Iterate over the slices, collecting the result
 132     let mut ret = 0;
 133     for (i, j) in a_slice.iter().zip(b_slice.iter()) {
 134         ret += (*i) * (*j);
 135     }
 136     return ret;
 137 }
 138
 139 #[lang = "panic_fmt"]
 140 extern fn panic_fmt(args: &core::fmt::Arguments,
 141                     file: &str,
 142                     line: u32) -> ! {
 143     loop {}
 144 }
 145
 146 #[lang = "eh_personality"] extern fn eh_personality() {}
 147 # #[start] fn start(argc: isize, argv: *const *const u8) -> isize { 0 }
 148 # #[lang = "eh_unwind_resume"] extern fn rust_eh_unwind_resume() {}
 149 # #[no_mangle] pub extern fn rust_eh_register_frames () {}
 150 # #[no_mangle] pub extern fn rust_eh_unregister_frames () {}
 151 # fn main() {}
 152 ```
 153
 154 Note that there is one lang item here whose signature differs from the examples
 155 above, `panic_fmt`. This must be defined by consumers of libcore because the
 156 core library declares panics, but it does not define it. The `panic_fmt`
 157 lang item is this crate's definition of panic, and it must be guaranteed to
 158 never return.
 159
 160 As can be seen in this example, the core library is intended to provide the
 161 power of Rust in all circumstances, regardless of platform requirements. Further
 162 libraries, such as liballoc, add functionality to libcore which make other
 163 platform-specific assumptions, but continue to be more portable than the
 164 standard library itself.
 165