Switch to llvm-strip, advocate its use.

Using binutils strip with lld breaks RelRO. Switch to llvm-strip to
avoid this issue.

This doesn't affect Gradle users because the Android Gradle Plugin
performs its own stripping. Gradle users will need to upgrade to
AGP 3.6 or newer (the change to fix the plugin has not yet been
submitted, but is in review).

Test: ./checkbuild.py && ./run_tests.py
Test: Compare sizes of all test outputs before and after, no changes
Bug: https://github.com/android-ndk/ndk/issues/843
Change-Id: I6710d0bc5dbbdc53bc3a66acccc6ba3d9c9a00f6

2 files changed, 45 insertions, 1 deletions

diff --git a/docs/BuildSystemMaintainers.md b/docs/BuildSystemMaintainers.md
index 2d7586c6b..a0ee50f3f 100644
--- a/docs/BuildSystemMaintainers.md
+++ b/docs/BuildSystemMaintainers.md
@@ -215,7 +215,37 @@ installed to the triple directory and is not triple-prefixed, but rather is only
 installed as `<NDK>/toolchains/llvm/prebuilt/<host-tag>/bin/ld.lld` because the
 one binary supports all ABIs.
 
+Warning: Using LLD with GNU `strip` or `objcopy` breaks RelRO. LLVM `strip` and
+`objcopy` must be used with LLD. See [Issue 843] and the [Binutils] section of
+this document for more information.
+
 [Issue 70838247]: https://issuetracker.google.com/70838247
+[Issue 843]: https://github.com/android-ndk/ndk/issues/843
+
+## Binutils
+
+GNU Binutils tools are installed to
+`<NDK>/toolchains/llvm/prebuilt/<host-tag>/bin/<triple>-<tool>` and
+`<NDK>/toolchains/llvm/prebuilt/<host-tag>/<triple>/bin/<tool>`. These include
+but are not limited to:
+
+ * ar
+ * as
+ * objcopy
+ * objdump
+ * readelf
+ * strip
+
+For some of these tools, LLVM equivalents are available. They typically have the
+same name but are prefixed with `llvm-`. For example, `llvm-strip` is used
+instead of `<triple>-strip` or the `strip` binary from the triple-specific
+direcory.
+
+Note: In general Android is moving away from GNU Binutils in favor of LLVM
+tools. This is a work in progress, but it is likely that a future release of the
+NDK will deprecate and eventually remove GNU Binutils. For now, ensure that your
+build system works with `llvm-strip` and `llvm-objcopy` as they are required
+when using LLD ([Issue 843]).
 
 ## Sysroot
 
diff --git a/docs/changelogs/Changelog-r21.md b/docs/changelogs/Changelog-r21.md
index f8399455b..b8da84910 100644
--- a/docs/changelogs/Changelog-r21.md
+++ b/docs/changelogs/Changelog-r21.md
@@ -20,7 +20,12 @@ For Android Studio issues, follow the docs on the [Android Studio site].
 
  * [LLD](https://lld.llvm.org/) is now available for testing. AOSP has switched
    to using LLD by default and the NDK will follow (timeline unknown). Test LLD
-   in your app by passing `-fuse-ld=lld` when linking.
+   in your app by passing `-fuse-ld=lld` when linking. Note that [Issue 843]
+   will affect builds using LLD with binutils strip and objcopy as opposed to
+   llvm-strip and llvm-objcopy.
+
+ * [Issue 843]: Build system maintainers should begin testing with llvm-strip
+   and llvm-objcopy. AOSP has switched to these and the NDK will follow.
 
  * The Play Store will require 64-bit support when uploading an APK beginning in
    August 2019. Start porting now to avoid surprises when the time comes. For
@@ -52,6 +57,10 @@ For Android Studio issues, follow the docs on the [Android Studio site].
    `-Wl,--build-id=sha1` instead of `-Wl,--build-id`. Third-party build systems
    need to apply the workaround manually. For more details, see the [Build
    System Maintainers Guide][maintainer_linkers].
+ * [Issue 843]: `llvm-strip` is now used instead of `strip` to avoid breaking
+   RelRO with LLD. Note that the Android Gradle Plugin performs its own
+   stripping, so most users will need to upgrade to Android Gradle Plugin
+   version 3.6 or newer to get the fix.
 
 [Issue 1004]: https://github.com/android-ndk/ndk/issues/1004
 [Issue 855]: https://github.com/android-ndk/ndk/issues/855
@@ -113,9 +122,14 @@ For Android Studio issues, follow the docs on the [Android Studio site].
    `No toolchains found in the NDK toolchains folder for ABI with prefix: mips64el-linux-android`,
    update your project file to [use plugin version 3.1 or newer]. You will also
    need to upgrade to Android Studio 3.1 or newer.
+ * [Issue 843]: Using LLD with binutils `strip` or `objcopy` breaks RelRO. Use
+   `llvm-strip` and `llvm-objcopy` instead. This issue has been resolved in
+   Android Gradle Plugin version 3.6 (for non-Gradle users, the fix is also in
+   ndk-build and our CMake toolchain file), but may affect other build systems.
 
 [Issue 360]: https://github.com/android-ndk/ndk/issues/360
 [Issue 70838247]: https://issuetracker.google.com/70838247
+[Issue 843]: https://github.com/android-ndk/ndk/issues/843
 [Issue 906]: https://github.com/android-ndk/ndk/issues/906
 [Issue 988]: https://github.com/android-ndk/ndk/issues/988
 [use plugin version 3.1 or newer]: https://developer.android.com/studio/releases/gradle-plugin#updating-plugin