From 2238b00dac093dce9614ead293cbc3fe66577787 Mon Sep 17 00:00:00 2001
From: Zalathar <Zalathar@users.noreply.github.com>
Date: Thu, 16 Jan 2025 12:53:46 +1100
Subject: [PATCH] Update docs for `-Clink-dead-code` to discourage its use
---
compiler/rustc_session/src/config.rs | 7 -------
compiler/rustc_session/src/options.rs | 2 +-
src/doc/rustc/src/codegen-options/index.md | 10 +++++-----
3 files changed, 6 insertions(+), 13 deletions(-)
diff --git a/compiler/rustc_session/src/config.rs b/compiler/rustc_session/src/config.rs
index 5192ad61af2b1..21afb7df7cb3a 100644
--- a/compiler/rustc_session/src/config.rs
+++ b/compiler/rustc_session/src/config.rs
@@ -132,13 +132,6 @@ pub enum LtoCli {
}
/// The different settings that the `-C instrument-coverage` flag can have.
-///
-/// 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, or including/excluding `-C link-dead-code`.
#[derive(Clone, Copy, PartialEq, Hash, Debug)]
pub enum InstrumentCoverage {
/// `-C instrument-coverage=no` (or `off`, `false` etc.)
diff --git a/compiler/rustc_session/src/options.rs b/compiler/rustc_session/src/options.rs
index 3af6df6301774..63aaa3abc8e56 100644
--- a/compiler/rustc_session/src/options.rs
+++ b/compiler/rustc_session/src/options.rs
@@ -1638,7 +1638,7 @@ options! {
"extra arguments to append to the linker invocation (space separated)"),
#[rustc_lint_opt_deny_field_access("use `Session::link_dead_code` instead of this field")]
link_dead_code: Option<bool> = (None, parse_opt_bool, [TRACKED],
- "keep dead code at link time (useful for code coverage) (default: no)"),
+ "try to generate and link dead code (default: no)"),
link_self_contained: LinkSelfContained = (LinkSelfContained::default(), parse_link_self_contained, [UNTRACKED],
"control whether to link Rust provided C objects/libraries or rely \
on a C toolchain or linker installed in the system"),
diff --git a/src/doc/rustc/src/codegen-options/index.md b/src/doc/rustc/src/codegen-options/index.md
index e987d06b0f31f..f45217c69ff0f 100644
--- a/src/doc/rustc/src/codegen-options/index.md
+++ b/src/doc/rustc/src/codegen-options/index.md
@@ -207,14 +207,14 @@ options should be separated by spaces.
## link-dead-code
-This flag controls whether the linker will keep dead code. It takes one of
-the following values:
+Tries to generate and link dead code that would otherwise not be generated or
+linked. It takes one of the following values:
-* `y`, `yes`, `on`, `true` or no value: keep dead code.
+* `y`, `yes`, `on`, `true` or no value: try to keep dead code.
* `n`, `no`, `off` or `false`: remove dead code (the default).
-An example of when this flag might be useful is when trying to construct code coverage
-metrics.
+This flag was historically used to help improve some older forms of code
+coverage measurement. Its use is not recommended.
## link-self-contained