From 9d0946acd0fe0498456ff7a0da208b546d9683b7 Mon Sep 17 00:00:00 2001
From: Joe Ranweiler <joe@lemma.co>
Date: Thu, 20 Jul 2017 15:05:10 -0700
Subject: [PATCH 1/2] Tell `tidy` about `compiler_builtins_lib` feature

After the work in #42899, it no longer auto-discovers it.
---
 src/tools/tidy/src/features.rs | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/src/tools/tidy/src/features.rs b/src/tools/tidy/src/features.rs
index 4c94ade98d965..301f0d1d80b79 100644
--- a/src/tools/tidy/src/features.rs
+++ b/src/tools/tidy/src/features.rs
@@ -219,6 +219,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 {

From e74f6114052524bbc2498b43713a8bf1114d14f8 Mon Sep 17 00:00:00 2001
From: Joe Ranweiler <joe@lemma.co>
Date: Wed, 19 Jul 2017 12:56:05 -0700
Subject: [PATCH 2/2] 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.
---
 .../src/language-features/lang-items.md       |  8 +++++
 .../library-features/compiler-builtins-lib.md | 35 +++++++++++++++++++
 2 files changed, 43 insertions(+)
 create mode 100644 src/doc/unstable-book/src/library-features/compiler-builtins-lib.md

diff --git a/src/doc/unstable-book/src/language-features/lang-items.md b/src/doc/unstable-book/src/language-features/lang-items.md
index a2368ee5f4ac5..ecbc860e25c03 100644
--- a/src/doc/unstable-book/src/language-features/lang-items.md
+++ b/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
diff --git a/src/doc/unstable-book/src/library-features/compiler-builtins-lib.md b/src/doc/unstable-book/src/library-features/compiler-builtins-lib.md
new file mode 100644
index 0000000000000..6c71c3f2ce191
--- /dev/null
+++ b/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;
+```