Rollup merge of #43342 - ranweiler:no-std-exe-docs, r=alexcrichton

Document use of `compiler_builtins` with `no_std` binaries

See discussion in #43264.

The docs for the `compiler_builtins_lib` feature were removed in
PR #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.

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

@@ -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

src/doc/unstable-book/src/library-features/compiler-builtins-lib.md

@@ -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;
+```

src/tools/tidy/src/features.rs

@@ -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 {