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.
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.
12 The function marked `#[start]` is passed the command line parameters
13 in the same format as C:
17 #![feature(lang_items)]
22 // Pull in the system libc library for what crt0.o likely requires
25 // Entry point for this program
27 fn start(_argc: isize, _argv: *const *const u8) -> isize {
31 // These functions and traits are used by the compiler, but not
32 // for a bare-bones hello world. These are normally
33 // provided by libstd.
34 #[lang = "eh_personality"] extern fn eh_personality() {}
35 #[lang = "panic_fmt"] fn panic_fmt() -> ! { loop {} }
36 # #[lang = "eh_unwind_resume"] extern fn rust_eh_unwind_resume() {}
37 # // fn main() {} tricked you, rustdoc!
40 To override the compiler-inserted `main` shim, one has to disable it
41 with `#![no_main]` and then create the appropriate symbol with the
42 correct ABI and the correct name, which requires overriding the
43 compiler's name mangling too:
48 #![feature(lang_items)]
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 {
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 # // fn main() {} tricked you, rustdoc!
67 The compiler currently makes a few assumptions about symbols which are available
68 in the executable to call. Normally these functions are provided by the standard
69 library, but without it you must define your own.
71 The first of these two functions, `eh_personality`, is used by the
72 failure mechanisms of the compiler. This is often mapped to GCC's
73 personality function (see the
74 [libstd implementation](../std/rt/unwind/index.html) for more
75 information), but crates which do not trigger a panic can be assured
76 that this function is never called. The second function, `panic_fmt`, is
77 also used by the failure mechanisms of the compiler.
81 > **Note**: the core library's structure is unstable, and it is recommended to
82 > use the standard library instead wherever possible.
84 With the above techniques, we've got a bare-metal executable running some Rust
85 code. There is a good deal of functionality provided by the standard library,
86 however, that is necessary to be productive in Rust. If the standard library is
87 not sufficient, then [libcore](../core/index.html) is designed to be used
90 The core library has very few dependencies and is much more portable than the
91 standard library itself. Additionally, the core library has most of the
92 necessary functionality for writing idiomatic and effective Rust code. When
93 using `#![no_std]`, Rust will automatically inject the `core` crate, just like
94 we do for `std` when we’re using it.
96 As an example, here is a program that will calculate the dot product of two
97 vectors provided from C, using idiomatic Rust practices.
101 #![feature(lang_items)]
105 #![feature(core_slice_ext)]
114 pub extern fn dot_product(a: *const u32, a_len: u32,
115 b: *const u32, b_len: u32) -> u32 {
116 use core::raw::Slice;
118 // Convert the provided arrays into Rust slices.
119 // The core::raw module guarantees that the Slice
120 // structure has the same memory layout as a &[T]
123 // This is an unsafe operation because the compiler
124 // cannot tell the pointers are valid.
125 let (a_slice, b_slice): (&[u32], &[u32]) = unsafe {
127 Slice { data: a, len: a_len as usize },
128 Slice { data: b, len: b_len as usize },
132 // Iterate over the slices, collecting the result
134 for (i, j) in a_slice.iter().zip(b_slice.iter()) {
140 #[lang = "panic_fmt"]
141 extern fn panic_fmt(args: &core::fmt::Arguments,
147 #[lang = "eh_personality"] extern fn eh_personality() {}
148 # #[lang = "eh_unwind_resume"] extern fn rust_eh_unwind_resume() {}
149 # #[start] fn start(argc: isize, argv: *const *const u8) -> isize { 0 }
153 Note that there is one extra lang item here which differs from the examples
154 above, `panic_fmt`. This must be defined by consumers of libcore because the
155 core library declares panics, but it does not define it. The `panic_fmt`
156 lang item is this crate's definition of panic, and it must be guaranteed to
159 As can be seen in this example, the core library is intended to provide the
160 power of Rust in all circumstances, regardless of platform requirements. Further
161 libraries, such as liballoc, add functionality to libcore which make other
162 platform-specific assumptions, but continue to be more portable than the
163 standard library itself.