Adjustments

Author: Mark-Simulacrum

posts/2022-04-07-Rust-1.60.0.md

@@ -25,18 +25,25 @@ the beta channel (`rustup default beta`) or the nightly channel (`rustup default
 
 ## What's in 1.60.0 stable
 
-### Instrumentation-based Code Coverage
+### Source-based Code Coverage
 
-Support for LLVM-based coverage instrumentation has been stabilized in rustc, enabled with `-C instrument-coverage`. You can try this out on your code by rebuilding your code with `-Cinstrument-coverage`:
+Support for LLVM-based coverage instrumentation has been stabilized in rustc. You can try this out on your code by rebuilding your code with `-Cinstrument-coverage`, for example like this:
 
 ```shell=
 RUSTFLAGS="-C instrument-coverage" cargo build
 ```
 
-After that, you can run the resulting binary, which will produce
-a `default.profraw` file in the current directory. That can be consumed
-by the `llvm-cov` binary shipped with rustc as part of the llvm-tools-preview
-component.
+After that, you can run the resulting binary, which will produce a
+`default.profraw` file in the current directory. (The path and filename can be
+overriden by an environment variable; see
+[documentation](https://doc.rust-lang.org/stable/rustc/instrument-coverage.html#running-the-instrumented-binary-to-generate-raw-coverage-profiling-data)
+for details).
+
+The `llvm-tools-preview` component includes `llvm-profdata` for processing and
+merging raw profile output (coverage region execution counts); and `llvm-cov`
+for report generation. `llvm-cov` combines the processed output, from
+`llvm-profdata`, and the binary itself, because the binary embeds a mapping from
+counters to actual source code regions.
 
 ```shell=
 rustup component add llvm-tools-preview
@@ -55,7 +62,13 @@ The above commands on a simple helloworld binary produce this annotated report,
     3|      1|}
 ```
 
-For more details, please read the [documentation](https://doc.rust-lang.org/rustc/instrument-coverage.html) in the rustc book. The specific output format and LLVM tooling to consume it are both not guaranteed to exist in this specific form, but the baseline functionality will continue to exist for future Rust releases.
+For more details, please read the
+[documentation](https://doc.rust-lang.org/rustc/instrument-coverage.html) in the
+rustc book. While the specific output format and LLVM tooling which produces it
+are subject to change, the baseline functionality is stable and will exist in
+some form in all future Rust releases. For this reason, it is important to make
+sure that you use the same version for both the `llvm-tools-preview` and the
+rustc binary used to compile your code.
 
 ### `cargo --timings`
 
@@ -87,7 +100,7 @@ parallel = ["jpeg-decoder/rayon"]
 ```
 
 There are two things to note in this example:
-* The optional dependency `jpeg-decoder` implicitly defines a feature of the same name. Enabling the `jpeg-decoder` feature will enable the `jpeg-decoder` dependency. 
+* The optional dependency `jpeg-decoder` implicitly defines a feature of the same name. Enabling the `jpeg-decoder` feature will enable the `jpeg-decoder` dependency.
 * The `"jpeg-decoder/rayon"` syntax enables the `jpeg-decoder` dependency *and* enables the `jpeg-decoder` dependency's `rayon` feature.
 
 Namespaced features tackles the first issue. You can now use the `dep:` prefix in the `[features]` table to explicitly refer to an optional dependency without implicitly exposing it as a feature. This gives you more control on how to define the feature corresponding to the optional dependency including hiding optional dependencies behind more descriptive feature names.
@@ -109,7 +122,7 @@ In this example, enabling the serde feature will enable the serde dependency. It
 
 ### Incremental compilation status
 
-Incremental compilation is re-enabled for the 1.60 release. The Rust team continues to work on fixing bugs in incremental, but no problems causing widespread breakage are known at this time, so we have chosen to reenable incremental compilation. Additionally, the compiler team is continuing to work on long-term strategy to avoid future problems of this kind. That process is in relatively early days, so we don't have anything to share yet on that front. 
+Incremental compilation is re-enabled for the 1.60 release. The Rust team continues to work on fixing bugs in incremental, but no problems causing widespread breakage are known at this time, so we have chosen to reenable incremental compilation. Additionally, the compiler team is continuing to work on long-term strategy to avoid future problems of this kind. That process is in relatively early days, so we don't have anything to share yet on that front.
 
 ### Stabilized APIs