squiid/rust
1
0
Fork 0
Code Issues Pull requests Projects Activity

Document use of compiler_builtins with no_std binaries

Browse source 
The docs for the `compiler_builtins_lib` library feature were removed
in #42899. But, though the `compiler_builtins` library has been
migrated out-of-tree, the feature remains, and is needed to use the
stand-alone crate. We reintroduce the docs for the feature, and add a
reference to them when describing how to create a `no_std` executable.
This commit is contained in:
Joe Ranweiler 2017-07-19 12:56:05 -07:00
parent 9d0946acd0
commit e74f611405
No known key found for this signature in database
GPG key ID: E0B6458CB03D167E
2 changed files with 43 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
src/doc/unstable-book/src/language-features/lang-items.md
View file

@ -194,6 +194,14 @@ pub extern fn rust_begin_panic(_msg: core::fmt::Arguments,
}
```
In many cases, you may need to manually link to the `compiler_builtins` crate
when building a `no_std` binary. You may observe this via linker error messages
such as "```undefined reference to `__rust_probestack'```". Using this crate
also requires enabling the library feature `compiler_builtins_lib`. You can read
more about this [here][compiler-builtins-lib].
[compiler-builtins-lib]: library-features/compiler-builtins-lib.html
## More about the language items
The compiler currently makes a few assumptions about symbols which are

35
src/doc/unstable-book/src/library-features/compiler-builtins-lib.md Normal file
View file

@ -0,0 +1,35 @@
# `compiler_builtins_lib`
The tracking issue for this feature is: None.
------------------------
This feature is required to link to the `compiler_builtins` crate which contains
"compiler intrinsics". Compiler intrinsics are software implementations of basic
operations like multiplication of `u64`s. These intrinsics are only required on
platforms where these operations don't directly map to a hardware instruction.
You should never need to explicitly link to the `compiler_builtins` crate when
building "std" programs as `compiler_builtins` is already in the dependency
graph of `std`. But you may need it when building `no_std` **binary** crates. If
you get a *linker* error like:
``` text
$PWD/src/main.rs:11: undefined reference to `__aeabi_lmul'
$PWD/src/main.rs:11: undefined reference to `__aeabi_uldivmod'
```
That means that you need to link to this crate.
When you link to this crate, make sure it only appears once in your crate
dependency graph. Also, it doesn't matter where in the dependency graph you
place the `compiler_builtins` crate.
<!-- NOTE(ignore) doctests don't support `no_std` binaries -->
``` rust,ignore
#![feature(compiler_builtins_lib)]
#![no_std]
extern crate compiler_builtins;
```