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