Update instrument-coverage documentation to document stability and LLVM versions

The instrument-coverage option is stable; the details of the profile
data format are not.

Recommend llvm-tools-preview as the preferred alternative to obtain a
compatible version of the LLVM tools, rather than finding LLVM tools
elsewhere.

2 files changed, 7 insertions, 3 deletions

diff --git a/src/doc/rustc/src/codegen-options/index.md b/src/doc/rustc/src/codegen-options/index.md
index d50c2317a0c..3b0cf92bbb7 100644
--- a/src/doc/rustc/src/codegen-options/index.md
+++ b/src/doc/rustc/src/codegen-options/index.md
@@ -182,6 +182,10 @@ The default depends on the [opt-level](#opt-level):
 This option enables instrumentation-based code coverage support. See the
 chapter on [instrumentation-based code coverage] for more information.
 
+Note that while the `-C instrument-coverage` option is stable, the profile data
+format produced by the resulting instrumentation may change, and may not work
+with coverage tools other than those built and shipped with the compiler.
+
 ## link-arg
 
 This flag lets you append a single extra argument to the linker invocation.
diff --git a/src/doc/rustc/src/instrument-coverage.md b/src/doc/rustc/src/instrument-coverage.md
index 53ab6e1db3e..3d817f14305 100644
--- a/src/doc/rustc/src/instrument-coverage.md
+++ b/src/doc/rustc/src/instrument-coverage.md
@@ -117,11 +117,11 @@ If `LLVM_PROFILE_FILE` contains a path to a non-existent directory, the missing
 
 ## Installing LLVM coverage tools
 
-LLVM's supplies two tools—`llvm-profdata` and `llvm-cov`—that process coverage data and generate reports. There are several ways to find and/or install these tools, but note that the coverage mapping data generated by the Rust compiler requires LLVM version 12 or higher. (`llvm-cov --version` typically shows the tool's LLVM version number.):
+LLVM's supplies two tools—`llvm-profdata` and `llvm-cov`—that process coverage data and generate reports. There are several ways to find and/or install these tools, but note that the coverage mapping data generated by the Rust compiler requires LLVM version 12 or higher, and processing the *raw* data may require exactly the LLVM version used by the compiler. (`llvm-cov --version` typically shows the tool's LLVM version number, and `rustc --verbose --version` shows the version of LLVM used by the Rust compiler.)
 
--   You can install the LLVM tools from your operating system distribution, or from your distribution of LLVM.
+-   You can install compatible versions of these tools via the `rustup` component `llvm-tools-preview`. This component is the recommended path, though it's still considered experimental. In this case, you may also find `cargo-binutils` useful as a wrapper around these tools.
+-   You can install a compatible version of LLVM tools from your operating system distribution, or from your distribution of LLVM.
 -   If you are building the Rust compiler from source, you can optionally use the bundled LLVM tools, built from source. Those tool binaries can typically be found in your build platform directory at something like: `rust/build/x86_64-unknown-linux-gnu/llvm/bin/llvm-*`.
--   You can install compatible versions of these tools via the `rustup` component `llvm-tools-preview`, though this is still considered experimental. In this case, you may also find `cargo-binutils` useful as a wrapper around these tools.
 
 The examples in this document show how to use the llvm tools directly.