Skip to content

Commit e74f611

Browse files
committed
Document use of compiler_builtins with no_std binaries
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.
1 parent 9d0946a commit e74f611

File tree

2 files changed

+43
-0
lines changed

2 files changed

+43
-0
lines changed

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

+8
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,14 @@ pub extern fn rust_begin_panic(_msg: core::fmt::Arguments,
194194
}
195195
```
196196

197+
In many cases, you may need to manually link to the `compiler_builtins` crate
198+
when building a `no_std` binary. You may observe this via linker error messages
199+
such as "```undefined reference to `__rust_probestack'```". Using this crate
200+
also requires enabling the library feature `compiler_builtins_lib`. You can read
201+
more about this [here][compiler-builtins-lib].
202+
203+
[compiler-builtins-lib]: library-features/compiler-builtins-lib.html
204+
197205
## More about the language items
198206

199207
The compiler currently makes a few assumptions about symbols which are
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# `compiler_builtins_lib`
2+
3+
The tracking issue for this feature is: None.
4+
5+
------------------------
6+
7+
This feature is required to link to the `compiler_builtins` crate which contains
8+
"compiler intrinsics". Compiler intrinsics are software implementations of basic
9+
operations like multiplication of `u64`s. These intrinsics are only required on
10+
platforms where these operations don't directly map to a hardware instruction.
11+
12+
You should never need to explicitly link to the `compiler_builtins` crate when
13+
building "std" programs as `compiler_builtins` is already in the dependency
14+
graph of `std`. But you may need it when building `no_std` **binary** crates. If
15+
you get a *linker* error like:
16+
17+
``` text
18+
$PWD/src/main.rs:11: undefined reference to `__aeabi_lmul'
19+
$PWD/src/main.rs:11: undefined reference to `__aeabi_uldivmod'
20+
```
21+
22+
That means that you need to link to this crate.
23+
24+
When you link to this crate, make sure it only appears once in your crate
25+
dependency graph. Also, it doesn't matter where in the dependency graph you
26+
place the `compiler_builtins` crate.
27+
28+
<!-- NOTE(ignore) doctests don't support `no_std` binaries -->
29+
30+
``` rust,ignore
31+
#![feature(compiler_builtins_lib)]
32+
#![no_std]
33+
34+
extern crate compiler_builtins;
35+
```

0 commit comments

Comments
 (0)