Stabilize -Z instrument-coverage as -C instrument-coverage

Continue supporting -Z instrument-coverage for compatibility for now,
but show a deprecation warning for it.

Update uses and documentation to use the -C option.

Move the documentation from the unstable book to stable rustc
documentation.

2 files changed, 43 insertions, 17 deletions

diff --git a/compiler/rustc_session/src/config.rs b/compiler/rustc_session/src/config.rs
index f2c7959ddb6..fa14a95bb0c 100644
--- a/compiler/rustc_session/src/config.rs
+++ b/compiler/rustc_session/src/config.rs
@@ -127,15 +127,15 @@ pub enum MirSpanview {
     Block,
 }
 
-/// The different settings that the `-Z instrument-coverage` flag can have.
+/// The different settings that the `-C instrument-coverage` flag can have.
 ///
-/// Coverage instrumentation now supports combining `-Z instrument-coverage`
+/// Coverage instrumentation now supports combining `-C instrument-coverage`
 /// with compiler and linker optimization (enabled with `-O` or `-C opt-level=1`
 /// and higher). Nevertheless, there are many variables, depending on options
 /// selected, code structure, and enabled attributes. If errors are encountered,
 /// either while compiling or when generating `llvm-cov show` reports, consider
 /// lowering the optimization level, including or excluding `-C link-dead-code`,
-/// or using `-Z instrument-coverage=except-unused-functions` or `-Z
+/// or using `-C instrument-coverage=except-unused-functions` or `-C
 /// instrument-coverage=except-unused-generics`.
 ///
 /// Note that `ExceptUnusedFunctions` means: When `mapgen.rs` generates the
@@ -148,13 +148,13 @@ pub enum MirSpanview {
 /// unless the function has type parameters.
 #[derive(Clone, Copy, PartialEq, Hash, Debug)]
 pub enum InstrumentCoverage {
-    /// Default `-Z instrument-coverage` or `-Z instrument-coverage=statement`
+    /// Default `-C instrument-coverage` or `-C instrument-coverage=statement`
     All,
-    /// `-Z instrument-coverage=except-unused-generics`
+    /// `-C instrument-coverage=except-unused-generics`
     ExceptUnusedGenerics,
-    /// `-Z instrument-coverage=except-unused-functions`
+    /// `-C instrument-coverage=except-unused-functions`
     ExceptUnusedFunctions,
-    /// `-Z instrument-coverage=off` (or `no`, etc.)
+    /// `-C instrument-coverage=off` (or `no`, etc.)
     Off,
 }
 
@@ -2144,18 +2144,37 @@ pub fn build_session_options(matches: &getopts::Matches) -> Options {
         _ => {}
     }
 
-    if debugging_opts.instrument_coverage.is_some()
-        && debugging_opts.instrument_coverage != Some(InstrumentCoverage::Off)
-    {
+    // Handle both `-Z instrument-coverage` and `-C instrument-coverage`; the latter takes
+    // precedence.
+    match (cg.instrument_coverage, debugging_opts.instrument_coverage) {
+        (Some(ic_c), Some(ic_z)) if ic_c != ic_z => {
+            early_error(
+                error_format,
+                "incompatible values passed for `-C instrument-coverage` \
+                and `-Z instrument-coverage`",
+            );
+        }
+        (None, None) => {}
+        (None, ic) => {
+            early_warn(
+                error_format,
+                "`-Z instrument-coverage` is deprecated; use `-C instrument-coverage`",
+            );
+            cg.instrument_coverage = ic;
+        }
+        _ => {}
+    }
+
+    if cg.instrument_coverage.is_some() && cg.instrument_coverage != Some(InstrumentCoverage::Off) {
         if cg.profile_generate.enabled() || cg.profile_use.is_some() {
             early_error(
                 error_format,
-                "option `-Z instrument-coverage` is not compatible with either `-C profile-use` \
+                "option `-C instrument-coverage` is not compatible with either `-C profile-use` \
                 or `-C profile-generate`",
             );
         }
 
-        // `-Z instrument-coverage` implies `-C symbol-mangling-version=v0` - to ensure consistent
+        // `-C instrument-coverage` implies `-C symbol-mangling-version=v0` - to ensure consistent
         // and reversible name mangling. Note, LLVM coverage tools can analyze coverage over
         // multiple runs, including some changes to source code; so mangled names must be consistent
         // across compilations.
@@ -2164,7 +2183,7 @@ pub fn build_session_options(matches: &getopts::Matches) -> Options {
             Some(SymbolManglingVersion::Legacy) => {
                 early_warn(
                     error_format,
-                    "-Z instrument-coverage requires symbol mangling version `v0`, \
+                    "-C instrument-coverage requires symbol mangling version `v0`, \
                     but `-C symbol-mangling-version=legacy` was specified",
                 );
             }
diff --git a/compiler/rustc_session/src/options.rs b/compiler/rustc_session/src/options.rs
index c8adc9f00a1..2b39d97d55b 100644
--- a/compiler/rustc_session/src/options.rs
+++ b/compiler/rustc_session/src/options.rs
@@ -109,17 +109,16 @@ impl Options {
     }
 
     pub fn instrument_coverage(&self) -> bool {
-        self.debugging_opts.instrument_coverage.unwrap_or(InstrumentCoverage::Off)
-            != InstrumentCoverage::Off
+        self.cg.instrument_coverage.unwrap_or(InstrumentCoverage::Off) != InstrumentCoverage::Off
     }
 
     pub fn instrument_coverage_except_unused_generics(&self) -> bool {
-        self.debugging_opts.instrument_coverage.unwrap_or(InstrumentCoverage::Off)
+        self.cg.instrument_coverage.unwrap_or(InstrumentCoverage::Off)
             == InstrumentCoverage::ExceptUnusedGenerics
     }
 
     pub fn instrument_coverage_except_unused_functions(&self) -> bool {
-        self.debugging_opts.instrument_coverage.unwrap_or(InstrumentCoverage::Off)
+        self.cg.instrument_coverage.unwrap_or(InstrumentCoverage::Off)
             == InstrumentCoverage::ExceptUnusedFunctions
     }
 }
@@ -1021,6 +1020,14 @@ options! {
         "enable incremental compilation"),
     inline_threshold: Option<u32> = (None, parse_opt_number, [TRACKED],
         "set the threshold for inlining a function"),
+    instrument_coverage: Option<InstrumentCoverage> = (None, parse_instrument_coverage, [TRACKED],
+        "instrument the generated code to support LLVM source-based code coverage \
+        reports (note, the compiler build config must include `profiler = true`); \
+        implies `-C symbol-mangling-version=v0`. Optional values are:
+        `=all` (implicit value)
+        `=except-unused-generics`
+        `=except-unused-functions`
+        `=off` (default)"),
     link_arg: (/* redirected to link_args */) = ((), parse_string_push, [UNTRACKED],
         "a single extra argument to append to the linker invocation (can be used several times)"),
     link_args: Vec<String> = (Vec::new(), parse_list, [UNTRACKED],