Skip to content

Commit

Permalink
Rollup merge of rust-lang#43342 - ranweiler:no-std-exe-docs, r=alexcr…
Browse files Browse the repository at this point in the history
…ichton

Document use of `compiler_builtins` with `no_std` binaries

See discussion in rust-lang#43264.

The docs for the `compiler_builtins_lib` feature were removed in
PR rust-lang#42899. But, though the `compiler_builtins` library has been
migrated out-of-tree, the language feature remains, and is needed to
use the stand-alone crate. So, we reintroduce the docs for the
feature, and add a reference to them when describing how to create a
`no_std` executable.
  • Loading branch information
Mark-Simulacrum authored Jul 24, 2017
2 parents da24118 + e74f611 commit 295a789
Show file tree
Hide file tree
Showing 3 changed files with 55 additions and 0 deletions.
8 changes: 8 additions & 0 deletions src/doc/unstable-book/src/language-features/lang-items.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -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;
```
12 changes: 12 additions & 0 deletions src/tools/tidy/src/features.rs
Original file line number Diff line number Diff line change
Expand Up @@ -247,6 +247,18 @@ pub fn collect_lang_features(base_src_path: &Path) -> Features {

pub fn collect_lib_features(base_src_path: &Path) -> Features {
let mut lib_features = Features::new();

// This library feature is defined in the `compiler_builtins` crate, which
// has been moved out-of-tree. Now it can no longer be auto-discovered by
// `tidy`, because we need to filter out its (submodule) directory. Manually
// add it to the set of known library features so we can still generate docs.
lib_features.insert("compiler_builtins_lib".to_owned(), Feature {
level: Status::Unstable,
since: "".to_owned(),
has_gate_test: false,
tracking_issue: None,
});

map_lib_features(base_src_path,
&mut |res, _, _| {
match res {
Expand Down

0 comments on commit 295a789

Please sign in to comment.