Auto merge of #136926 - wesleywiser:stabilize_dwarf-version, r=petrochenkov

Stabilize `-Zdwarf-version` as `-Cdwarf-version`

I propose stabilizing `-Zdwarf-version` as `-Cdwarf-version`. This PR adds a new `-Cdwarf-version` flag, leaving the unstable `-Z` flag as is to ease the transition period. The `-Z` flag will be removed in the future.

# `-Zdwarf-version` stabilization report

## What is the RFC for this feature and what changes have occurred to the user-facing design since the RFC was finalized?

No RFC/MCP, this flag was added in https://github.com/rust-lang/rust/pull/98350 and was not deemed large enough to require additional process.

The tracking issue for this feature is #103057.

## What behavior are we committing to that has been controversial? Summarize the major arguments pro/con.

None that has been extensively debated but there are a few questions that could have been chosen differently:

1. What should the flag name be?
  The current flag name is very specific to DWARF. Other debuginfo formats exist (msvc's CodeView format or https://en.wikipedia.org/wiki/Stabs) so we could have chosen to generalize the flag name (`-{C,Z} debuginfo-version=dwarf-5` for example). While this would extend cleanly to support formats other than DWARF, there are some downsides to this design. Neither CodeView nor Stabs have specification or format versions so it's not clear what values would be supported beyond `dwarf-{2,3,4,5}` or `codeview`. We would also need to take care to ensure the name does not lead users to think they can pick a format other than one supported by the target. For instance, what would `--target x86_64-pc-windows-msvc -Cdebuginfo-version=dwarf-5` do?

2. What is the behavior when flag is used on targets that do not support DWARF?
  Currently, passing `-{C,Z} dwarf-version` on targets like `*-windows-msvc` does not do anything. It may be preferable to emit a warning alerting the user that the flag has no effect on the target platform. Alternatively, we could emit an error but this could be annoying since it would require the use of target specific RUSTFLAGS to use the flag correctly (and there isn't a way to target "any platform that uses DWARF" using cfgs).

3. Does the precompiled standard library potentially using a different version of DWARF a problem?
  I don't believe this is an issue as debuggers (and other such tools) already must deal with the possibility that an application uses different DWARF versions across its statically or dynamically linked libraries.

## Are there extensions to this feature that remain unstable? How do we know that we are not accidentally committing to those.

No extensions per se, although future DWARF versions could be considered as such. At present, we validate the requested DWARF version is between 2 and 5 (inclusive) so new DWARF versions will not automatically be supported until the validation logic is adjusted.

## Summarize the major parts of the implementation and provide links into the code (or to PRs)

- Targets define their preferred or default DWARF version: https://github.com/rust-lang/rust/blob/34a5ea911c56e79bd451c63f04ea2f5023d7d1a3/compiler/rustc_target/src/spec/mod.rs#L2369
- We use the target default but this can be overriden by `-{C,Z} dwarf-version` https://github.com/rust-lang/rust/blob/34a5ea911c56e79bd451c63f04ea2f5023d7d1a3/compiler/rustc_session/src/session.rs#L738
- The flag is validated https://github.com/rust-lang/rust/blob/34a5ea911c56e79bd451c63f04ea2f5023d7d1a3/compiler/rustc_session/src/session.rs#L1253-L1258
- When debuginfo is generated, we tell LLVM to use the requested value or the target default https://github.com/rust-lang/rust/blob/34a5ea911c56e79bd451c63f04ea2f5023d7d1a3/compiler/rustc_codegen_llvm/src/debuginfo/mod.rs#L106

## Summarize existing test coverage of this feature

- Test that we actually generate the appropriate DWARF version
  - https://github.com/rust-lang/rust/blob/master/tests/assembly/dwarf5.rs
  - https://github.com/rust-lang/rust/blob/master/tests/assembly/dwarf4.rs
- Test that LTO with different DWARF versions picks the highest version
  - https://github.com/rust-lang/rust/blob/master/tests/assembly/dwarf-mixed-versions-lto.rs
- Test DWARF versions 2-5 are valid while 0, 1 and 6 report an error
  - https://github.com/rust-lang/rust/blob/master/tests/ui/debuginfo/dwarf-versions.rs
- Ensure LLVM does not report a warning when LTO'ing different DWARF versions together
  - https://github.com/rust-lang/rust/blob/master/tests/ui/lto/dwarf-mixed-versions-lto.rs

## Has a call-for-testing period been conducted? If so, what feedback was received?

No call-for-testing has been conducted but Rust for Linux has been using this flag without issue.

## What outstanding bugs in the issue tracker involve this feature? Are they stabilization-blocking?

All reported bugs have been resolved.

## Summarize contributors to the feature by name for recognition and assuredness that people involved in the feature agree with stabilization

- Initial implementation in https://github.com/rust-lang/rust/pull/98350 by `@pcwalton`
- Stop emitting `.debug_pubnames` and `.debug_pubtypes` when using DWARF 5 in https://github.com/rust-lang/rust/pull/117962 by `@weihanglo.`
- Refactoring & cleanups (#135739), fix LLVM warning on LTO with different DWARF versions (#136659) and argument validation (#136746) by `@wesleywiser`

## What FIXMEs are still in the code for that feature and why is it ok to leave them there?

No FIXMEs related to this feature.

## What static checks are done that are needed to prevent undefined behavior?

This feature cannot cause undefined behavior.
We ensure the DWARF version is one of the supported values [here](https://github.com/rust-lang/rust/blob/34a5ea911c56e79bd451c63f04ea2f5023d7d1a3/compiler/rustc_session/src/session.rs#L1255-L1257).

## In what way does this feature interact with the reference/specification, and are those edits prepared?

No changes to reference/spec, unstable rustc docs are moved to the stable book as part of the stabilization PR.

## Does this feature introduce new expressions and can they produce temporaries? What are the lifetimes of those temporaries?

No.

## What other unstable features may be exposed by this feature?

`-Zembed-source` requires use of DWARF 5 extensions but has its own feature gate.

## What is tooling support like for this feature, w.r.t rustdoc, clippy, rust-analzyer, rustfmt, etc.?

No support needed for rustdoc, clippy, rust-analyzer, rustfmt or rustup.

Cargo could expose this as an option in build profiles but I would expect the decision as to what version should be used would be made for the entire crate graph at build time rather than by individual package authors.

cc-rs has support for detecting the presence of `-{C,Z} dwarf-version` in `RUSTFLAGS` and providing the corresponding flag to Clang/gcc (https://github.com/rust-lang/cc-rs/pull/1395).

---

Closes #103057

13 files changed, 42 insertions, 32 deletions

diff --git a/compiler/rustc_interface/src/tests.rs b/compiler/rustc_interface/src/tests.rs
index 75a1b61b416..d405d044cae 100644
--- a/compiler/rustc_interface/src/tests.rs
+++ b/compiler/rustc_interface/src/tests.rs
@@ -614,6 +614,7 @@ fn test_codegen_options_tracking_hash() {
     tracked!(control_flow_guard, CFGuard::Checks);
     tracked!(debug_assertions, Some(true));
     tracked!(debuginfo, DebugInfo::Limited);
+    tracked!(dwarf_version, Some(5));
     tracked!(embed_bitcode, false);
     tracked!(force_frame_pointers, FramePointer::Always);
     tracked!(force_unwind_tables, Some(true));
diff --git a/compiler/rustc_session/src/options.rs b/compiler/rustc_session/src/options.rs
index c70f1500d39..ea3a1f8bd8c 100644
--- a/compiler/rustc_session/src/options.rs
+++ b/compiler/rustc_session/src/options.rs
@@ -1956,6 +1956,9 @@ options! {
         "allow the linker to link its default libraries (default: no)"),
     dlltool: Option<PathBuf> = (None, parse_opt_pathbuf, [UNTRACKED],
         "import library generation tool (ignored except when targeting windows-gnu)"),
+    #[rustc_lint_opt_deny_field_access("use `Session::dwarf_version` instead of this field")]
+    dwarf_version: Option<u32> = (None, parse_opt_number, [TRACKED],
+        "version of DWARF debug information to emit (default: 2 or 4, depending on platform)"),
     embed_bitcode: bool = (true, parse_bool, [TRACKED],
         "emit bitcode in rlibs (default: yes)"),
     extra_filename: String = (String::new(), parse_string, [UNTRACKED],
diff --git a/compiler/rustc_session/src/session.rs b/compiler/rustc_session/src/session.rs
index 1359f7eb7bb..010ae42c280 100644
--- a/compiler/rustc_session/src/session.rs
+++ b/compiler/rustc_session/src/session.rs
@@ -764,7 +764,11 @@ impl Session {
 
     /// Returns the DWARF version passed on the CLI or the default for the target.
     pub fn dwarf_version(&self) -> u32 {
-        self.opts.unstable_opts.dwarf_version.unwrap_or(self.target.default_dwarf_version)
+        self.opts
+            .cg
+            .dwarf_version
+            .or(self.opts.unstable_opts.dwarf_version)
+            .unwrap_or(self.target.default_dwarf_version)
     }
 
     pub fn stack_protector(&self) -> StackProtector {
@@ -1327,7 +1331,9 @@ fn validate_commandline_args_with_session_available(sess: &Session) {
         sess.dcx().emit_err(errors::BranchProtectionRequiresAArch64);
     }
 
-    if let Some(dwarf_version) = sess.opts.unstable_opts.dwarf_version {
+    if let Some(dwarf_version) =
+        sess.opts.cg.dwarf_version.or(sess.opts.unstable_opts.dwarf_version)
+    {
         // DWARF 1 is not supported by LLVM and DWARF 6 is not yet finalized.
         if dwarf_version < 2 || dwarf_version > 5 {
             sess.dcx().emit_err(errors::UnsupportedDwarfVersion { dwarf_version });
diff --git a/src/doc/rustc/src/codegen-options/index.md b/src/doc/rustc/src/codegen-options/index.md
index 8c1769a8c77..a3b70e7f977 100644
--- a/src/doc/rustc/src/codegen-options/index.md
+++ b/src/doc/rustc/src/codegen-options/index.md
@@ -110,6 +110,19 @@ It takes a path to [the dlltool executable](https://sourceware.org/binutils/docs
 If this flag is not specified, a dlltool executable will be inferred based on
 the host environment and target.
 
+## dwarf-version
+
+This option controls the version of DWARF that the compiler emits, on platforms
+that use DWARF to encode debug information. It takes one of the following
+values:
+
+* `2`: DWARF version 2 (the default on certain platforms, like Android).
+* `3`: DWARF version 3 (the default on certain platforms, like AIX).
+* `4`: DWARF version 4 (the default on most platforms, like Linux & macOS).
+* `5`: DWARF version 5.
+
+DWARF version 1 is not supported.
+
 ## embed-bitcode
 
 This flag controls whether or not the compiler embeds LLVM bitcode into object
diff --git a/src/doc/unstable-book/src/compiler-flags/dwarf-version.md b/src/doc/unstable-book/src/compiler-flags/dwarf-version.md
deleted file mode 100644
index e88799d2cf0..00000000000
--- a/src/doc/unstable-book/src/compiler-flags/dwarf-version.md
+++ /dev/null
@@ -1,13 +0,0 @@
-## `dwarf-version`
-
-The tracking issue for this feature is: <https://github.com/rust-lang/rust/issues/103057>
-
-----------------------------
-
-This option controls the version of DWARF that the compiler emits, on platforms
-that use DWARF to encode debug information. It takes one of the following
-values:
-
-* `2`: DWARF version 2 (the default on certain platforms, like macOS).
-* `4`: DWARF version 4 (the default on certain platforms, like Linux).
-* `5`: DWARF version 5.
diff --git a/tests/assembly/auxiliary/dwarf-mixed-versions-lto-aux.rs b/tests/assembly/auxiliary/dwarf-mixed-versions-lto-aux.rs
index faff6e7e2d0..257608f881f 100644
--- a/tests/assembly/auxiliary/dwarf-mixed-versions-lto-aux.rs
+++ b/tests/assembly/auxiliary/dwarf-mixed-versions-lto-aux.rs
@@ -1,4 +1,4 @@
-//@ compile-flags: -g --crate-type=rlib -Zdwarf-version=4
+//@ compile-flags: -g --crate-type=rlib -Cdwarf-version=4
 
 pub fn check_is_even(number: &u64) -> bool {
     number % 2 == 0
diff --git a/tests/assembly/dwarf-mixed-versions-lto.rs b/tests/assembly/dwarf-mixed-versions-lto.rs
index f1fc0814c9d..9910a6e2f5f 100644
--- a/tests/assembly/dwarf-mixed-versions-lto.rs
+++ b/tests/assembly/dwarf-mixed-versions-lto.rs
@@ -4,7 +4,7 @@
 
 //@ only-linux
 //@ aux-build:dwarf-mixed-versions-lto-aux.rs
-//@ compile-flags: -C lto -g -Zdwarf-version=5
+//@ compile-flags: -C lto -g -Cdwarf-version=5
 //@ assembly-output: emit-asm
 //@ no-prefer-dynamic
 
diff --git a/tests/assembly/dwarf4.rs b/tests/assembly/dwarf4.rs
index 6013adf3386..03a388603b4 100644
--- a/tests/assembly/dwarf4.rs
+++ b/tests/assembly/dwarf4.rs
@@ -1,7 +1,7 @@
-// Makes sure that `-Z dwarf-version=4` causes `rustc` to emit DWARF version 4.
+// Makes sure that `-C dwarf-version=4` causes `rustc` to emit DWARF version 4.
 //@ assembly-output: emit-asm
 //@ add-core-stubs
-//@ compile-flags: -g --target x86_64-unknown-linux-gnu -Z dwarf-version=4 -Copt-level=0
+//@ compile-flags: -g --target x86_64-unknown-linux-gnu -C dwarf-version=4 -Copt-level=0
 //@ needs-llvm-components: x86
 
 #![feature(no_core, lang_items)]
diff --git a/tests/assembly/dwarf5.rs b/tests/assembly/dwarf5.rs
index 9cd596e7834..9bd92cc0d09 100644
--- a/tests/assembly/dwarf5.rs
+++ b/tests/assembly/dwarf5.rs
@@ -1,7 +1,7 @@
-// Makes sure that `-Z dwarf-version=5` causes `rustc` to emit DWARF version 5.
+// Makes sure that `-C dwarf-version=5` causes `rustc` to emit DWARF version 5.
 //@ add-core-stubs
 //@ assembly-output: emit-asm
-//@ compile-flags: -g --target x86_64-unknown-linux-gnu -Z dwarf-version=5 -Copt-level=0
+//@ compile-flags: -g --target x86_64-unknown-linux-gnu -C dwarf-version=5 -Copt-level=0
 //@ needs-llvm-components: x86
 
 #![feature(no_core, lang_items)]
diff --git a/tests/run-make/embed-source-dwarf/rmake.rs b/tests/run-make/embed-source-dwarf/rmake.rs
index 0aae07ff2e6..550c8b9b3c9 100644
--- a/tests/run-make/embed-source-dwarf/rmake.rs
+++ b/tests/run-make/embed-source-dwarf/rmake.rs
@@ -21,7 +21,7 @@ fn main() {
         .output(&output)
         .arg("-g")
         .arg("-Zembed-source=yes")
-        .arg("-Zdwarf-version=5")
+        .arg("-Cdwarf-version=5")
         .run();
     let output = rfs::read(output);
     let obj = object::File::parse(output.as_slice()).unwrap();
diff --git a/tests/ui/debuginfo/dwarf-versions.rs b/tests/ui/debuginfo/dwarf-versions.rs
index bb18cadce43..8f731f10ead 100644
--- a/tests/ui/debuginfo/dwarf-versions.rs
+++ b/tests/ui/debuginfo/dwarf-versions.rs
@@ -1,25 +1,25 @@
 // This test verifies the expected behavior of various options passed to
-// `-Zdwarf-version`: 2 - 5 (valid) with all other options being invalid.
+// `-Cdwarf-version`: 2 - 5 (valid) with all other options being invalid.
 
 //@ revisions: zero one two three four five six
 
-//@[zero] compile-flags: -Zdwarf-version=0
+//@[zero] compile-flags: -Cdwarf-version=0
 
-//@[one] compile-flags: -Zdwarf-version=1
+//@[one] compile-flags: -Cdwarf-version=1
 
-//@[two] compile-flags: -Zdwarf-version=2
+//@[two] compile-flags: -Cdwarf-version=2
 //@[two] check-pass
 
-//@[three] compile-flags: -Zdwarf-version=3
+//@[three] compile-flags: -Cdwarf-version=3
 //@[three] check-pass
 
-//@[four] compile-flags: -Zdwarf-version=4
+//@[four] compile-flags: -Cdwarf-version=4
 //@[four] check-pass
 
-//@[five] compile-flags: -Zdwarf-version=5
+//@[five] compile-flags: -Cdwarf-version=5
 //@[five] check-pass
 
-//@[six] compile-flags: -Zdwarf-version=6
+//@[six] compile-flags: -Cdwarf-version=6
 
 //@ compile-flags: -g --target x86_64-unknown-linux-gnu --crate-type cdylib
 //@ needs-llvm-components: x86
diff --git a/tests/ui/lto/auxiliary/dwarf-mixed-versions-lto-aux.rs b/tests/ui/lto/auxiliary/dwarf-mixed-versions-lto-aux.rs
index 3c81127ee65..2f2bf57f42b 100644
--- a/tests/ui/lto/auxiliary/dwarf-mixed-versions-lto-aux.rs
+++ b/tests/ui/lto/auxiliary/dwarf-mixed-versions-lto-aux.rs
@@ -1,4 +1,4 @@
-//@ compile-flags: -g --crate-type=rlib -Zdwarf-version=4
+//@ compile-flags: -g --crate-type=rlib -Cdwarf-version=4
 
 pub fn say_hi() {
     println!("hello there")
diff --git a/tests/ui/lto/dwarf-mixed-versions-lto.rs b/tests/ui/lto/dwarf-mixed-versions-lto.rs
index 14ef65a868e..900274eb22f 100644
--- a/tests/ui/lto/dwarf-mixed-versions-lto.rs
+++ b/tests/ui/lto/dwarf-mixed-versions-lto.rs
@@ -4,7 +4,7 @@
 
 //@ ignore-msvc Platform must use DWARF
 //@ aux-build:dwarf-mixed-versions-lto-aux.rs
-//@ compile-flags: -C lto -g -Zdwarf-version=5
+//@ compile-flags: -C lto -g -Cdwarf-version=5
 //@ no-prefer-dynamic
 //@ build-pass