Skip to content

Implement support for DWARF version 5. #98350

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 9, 2022
Merged

Conversation

pcwalton
Copy link
Contributor

@pcwalton pcwalton commented Jun 21, 2022

DWARF version 5 brings a number of improvements over version 4. Quoting from
the announcement 1:

Version 5 incorporates improvements in many areas: better data compression,
separation of debugging data from executable files, improved description of
macros and source files, faster searching for symbols, improved debugging
optimized code, as well as numerous improvements in functionality and
performance.

On platforms where DWARF version 5 is supported (Linux, primarily), this commit
adds support for it behind a new -Z dwarf-version=5 flag.

r? @michaelwoerister

@rustbot rustbot added the T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. label Jun 21, 2022
@rust-highfive
Copy link
Contributor

⚠️ Warning ⚠️

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jun 21, 2022
@rust-log-analyzer

This comment has been minimized.

@nikic
Copy link
Contributor

nikic commented Jun 21, 2022

This should probably be an unstable -Z dwarf-version flag, unless you intend this to be insta-stable.

Is the max dwarf version logic really needed? It seems odd that there is no way to force a newer version if a target has this option set. It's reasonable that some platforms default to an older version, but I don't really see a reason to hard forbid using a newer one (for example, if I bring my own toolchain).

@pcwalton pcwalton force-pushed the dwarf5 branch 2 times, most recently from 3e54d38 to 6c73840 Compare June 21, 2022 22:30
@pcwalton
Copy link
Contributor Author

OK, I've switched the -C flag to a -Z flag, removed the max_dwarf_version field from the target info, and moved the documentation over to the unstable book.

@nnethercote
Copy link
Contributor

Is this worth a perf run?

Copy link
Contributor

@nikic nikic left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks reasonable to me.

@michaelwoerister
Copy link
Member

Thanks, @pcwalton! Looks good to me.

@bors r+

Is this worth a perf run?

As it currently is, the PR does not actually change the DWARF version being used for anything. It just adds the -Z flag for explicitly setting it. So, we shouldn't see a perf difference. But once this is merged it would be interesting to see how switching to v5 affects performance.

@bors
Copy link
Collaborator

bors commented Jun 22, 2022

📌 Commit 6c73840877fb5db8fd84c431d7078abe23cd8f87 has been approved by michaelwoerister

@bors
Copy link
Collaborator

bors commented Jun 22, 2022

🌲 The tree is currently closed for pull requests below priority 1000. This pull request will be tested once the tree is reopened.

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jun 22, 2022
@pcwalton
Copy link
Contributor Author

Addressed comment. I think I need another review for bors to pick it up, r? @michaelwoerister

@nikic
Copy link
Contributor

nikic commented Jun 22, 2022

@bors r=michaelwoerister

@bors
Copy link
Collaborator

bors commented Jun 22, 2022

📌 Commit 42eeb58 has been approved by michaelwoerister

@bors
Copy link
Collaborator

bors commented Jun 22, 2022

🌲 The tree is currently closed for pull requests below priority 1000. This pull request will be tested once the tree is reopened.

@rust-log-analyzer

This comment has been minimized.

@pcwalton
Copy link
Contributor Author

Doesn't look related to this PR.

@nnethercote
Copy link
Contributor

That failure is the one that caused the tree closure. Should be resolved now.

@bors retry

@michaelwoerister
Copy link
Member

@bors retry

@michaelwoerister
Copy link
Member

@bors r+

bors added a commit to rust-lang-ci/rust that referenced this pull request Jul 9, 2022
Rollup of 7 pull requests

Successful merges:

 - rust-lang#98350 (Implement support for DWARF version 5.)
 - rust-lang#98915 (Clarify deriving code)
 - rust-lang#98980 (fix ICE in ConstProp)
 - rust-lang#99008 (Adding suggestion for E0530)
 - rust-lang#99043 (Collapse some weirdly-wrapping derives)
 - rust-lang#99048 (Remove a string comparison about types)
 - rust-lang#99070 (Update integer_atomics tracking issue)

Failed merges:

r? `@ghost`
`@rustbot` modify labels: rollup
@bors bors merged commit fd4f11d into rust-lang:master Jul 9, 2022
@rustbot rustbot added this to the 1.64.0 milestone Jul 9, 2022
glandium added a commit to glandium/cc-rs that referenced this pull request Jul 12, 2022
Rustc defaults to DWARF-2 on some targets, and DWARF-4 on others.
However using -g with the C compiler yields whatever default version the
C compiler prefers.

One side effect is that the DWARF debug info shipped in some libraries
with rustc itself (e.g. libcompiler_builtins and others) have recently
switched to DWARF-5 as a side effect of upgrading the clang version
used on rustc CI. (rust-lang/rust#98746)

Ideally, the preferred DWARF version would be given by the rust compiler
and/or cargo, but that's not the case at the moment, so the next best
thing is something that aligns with the current defaults, although
work in under way to add a rustc flag that would allow to pick the
preferred DWARF version (rust-lang/rust#98350)
glandium added a commit to glandium/cc-rs that referenced this pull request Jul 12, 2022
Rustc defaults to DWARF-2 on some targets, and DWARF-4 on others.
However using -g with the C compiler yields whatever default version the
C compiler prefers.

One side effect is that the DWARF debug info shipped in some libraries
with rustc itself (e.g. libcompiler_builtins and others) have recently
switched to DWARF-5 as a side effect of upgrading the clang version
used on rustc CI. (rust-lang/rust#98746)

Ideally, the preferred DWARF version would be given by the rust compiler
and/or cargo, but that's not the case at the moment, so the next best
thing is something that aligns with the current defaults, although
work in under way to add a rustc flag that would allow to pick the
preferred DWARF version (rust-lang/rust#98350)
Comment on lines -106 to +113
if let Some(version) = sess.target.dwarf_version {
llvm::LLVMRustAddModuleFlag(
self.llmod,
llvm::LLVMModFlagBehavior::Warning,
"Dwarf Version\0".as_ptr().cast(),
version,
)
}
let dwarf_version =
sess.opts.debugging_opts.dwarf_version.unwrap_or(sess.target.default_dwarf_version);
llvm::LLVMRustAddModuleFlag(
self.llmod,
llvm::LLVMModFlagBehavior::Warning,
"Dwarf Version\0".as_ptr().cast(),
dwarf_version,
);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could this have caused #99143? Looks like before this PR, we only ever set Dwarf Version on targets with Some in their dwarf_version, which based on the diff in this PR, wasn't the case for e.g. Windows (at least, there's probably more targets not covered by the ${OS}_base.rs files).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alright that was confusing but I'm pretty sure (#99143 (comment)) that what's going on is even with debuginfo disabled for a binary, the standard library is getting statically linked in and we ship it w/ debuginfo.

I'm not sure what the best approach here would be, maybe just relying on the is_like_msvc check to effectively switch between CodeView and Dwarf Version (and never set both)?

bors added a commit to rust-lang-ci/rust that referenced this pull request Jul 14, 2022
fix dwarf debuginfo being used in addition to CodeView on windows

Tackles the debuginfo size increase regression on windows to [unblock clippy](rust-lang#99143 (comment)) -- introduced by the DWARF5 support in rust-lang#98350 cc `@pcwalton.`

r? `@eddyb`
Fixes rust-lang#99143
@Wyvern
Copy link

Wyvern commented Jul 15, 2022

Does macOS support DWARF5 at the moment?

glandium added a commit to glandium/cc-rs that referenced this pull request Nov 10, 2022
Rustc defaults to DWARF-2 on some targets, and DWARF-4 on others.
However using -g with the C compiler yields whatever default version the
C compiler prefers.

One side effect is that the DWARF debug info shipped in some libraries
with rustc itself (e.g. libcompiler_builtins and others) have recently
switched to DWARF-5 as a side effect of upgrading the clang version
used on rustc CI. (rust-lang/rust#98746)

Ideally, the preferred DWARF version would be given by the rust compiler
and/or cargo, but that's not the case at the moment, so the next best
thing is something that aligns with the current defaults, although
work in under way to add a rustc flag that would allow to pick the
preferred DWARF version (rust-lang/rust#98350)
thomcc pushed a commit to rust-lang/cc-rs that referenced this pull request Nov 10, 2022
Rustc defaults to DWARF-2 on some targets, and DWARF-4 on others.
However using -g with the C compiler yields whatever default version the
C compiler prefers.

One side effect is that the DWARF debug info shipped in some libraries
with rustc itself (e.g. libcompiler_builtins and others) have recently
switched to DWARF-5 as a side effect of upgrading the clang version
used on rustc CI. (rust-lang/rust#98746)

Ideally, the preferred DWARF version would be given by the rust compiler
and/or cargo, but that's not the case at the moment, so the next best
thing is something that aligns with the current defaults, although
work in under way to add a rustc flag that would allow to pick the
preferred DWARF version (rust-lang/rust#98350)
fbq pushed a commit to Rust-for-Linux/linux that referenced this pull request Feb 17, 2024
Rust 1.64.0 introduced (unstable) support for the `-Zdwarf-version`
flag, which allows to select DWARFv5, thus use it.

Link: rust-lang/rust#103057
Link: rust-lang/rust#98350
Signed-off-by: Miguel Ojeda <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
fbq pushed a commit to Rust-for-Linux/linux that referenced this pull request Feb 19, 2024
Rust 1.64.0 introduced (unstable) support for the `-Zdwarf-version`
flag, which allows to select DWARFv5, thus use it.

Link: rust-lang/rust#103057
Link: rust-lang/rust#98350
Signed-off-by: Miguel Ojeda <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
fbq pushed a commit to Rust-for-Linux/linux that referenced this pull request Mar 5, 2024
Rust 1.64.0 introduced (unstable) support for the `-Zdwarf-version`
flag, which allows to select DWARFv5, thus use it.

Link: rust-lang/rust#103057
Link: rust-lang/rust#98350
Signed-off-by: Miguel Ojeda <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
fbq pushed a commit to Rust-for-Linux/linux that referenced this pull request Mar 25, 2024
Rust 1.64.0 introduced (unstable) support for the `-Zdwarf-version`
flag, which allows to select DWARFv5, thus use it.

Link: rust-lang/rust#103057
Link: rust-lang/rust#98350
Signed-off-by: Miguel Ojeda <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
ojeda added a commit to ojeda/linux that referenced this pull request Mar 29, 2024
Rust 1.64.0 introduced (unstable) support for the `-Zdwarf-version`
flag, which allows to select DWARFv5, thus use it.

Link: rust-lang/rust#103057
Link: rust-lang/rust#98350
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Miguel Ojeda <[email protected]>
ojeda added a commit to Rust-for-Linux/linux that referenced this pull request Mar 29, 2024
Rust 1.64.0 introduced (unstable) support for the `-Zdwarf-version`
flag, which allows to select DWARFv5, thus use it.

Link: rust-lang/rust#103057
Link: rust-lang/rust#98350
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Miguel Ojeda <[email protected]>
ojeda added a commit to Rust-for-Linux/linux that referenced this pull request Apr 2, 2024
Rust 1.64.0 introduced (unstable) support for the `-Zdwarf-version`
flag, which allows to select DWARFv5, thus use it.

Link: rust-lang/rust#103057
Link: rust-lang/rust#98350
Reviewed-by: Alice Ryhl <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Miguel Ojeda <[email protected]>
sweettea pushed a commit to sweettea/btrfs-fscrypt that referenced this pull request Apr 3, 2024
Rust 1.64.0 introduced (unstable) support for the `-Zdwarf-version`
flag, which allows to select DWARFv5, thus use it.

Link: rust-lang/rust#103057
Link: rust-lang/rust#98350
Reviewed-by: Alice Ryhl <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Miguel Ojeda <[email protected]>
Zalathar added a commit to Zalathar/rust that referenced this pull request Apr 16, 2025
…n, 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 rust-lang#98350 and was not deemed large enough to require additional process.

The tracking issue for this feature is rust-lang#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 rust-lang#98350 by `@pcwalton`
- Stop emitting `.debug_pubnames` and `.debug_pubtypes` when using DWARF 5 in rust-lang#117962 by `@weihanglo.`
- Refactoring & cleanups (rust-lang#135739), fix LLVM warning on LTO with different DWARF versions (rust-lang#136659) and argument validation (rust-lang#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 (rust-lang/cc-rs#1395).

---

Closes rust-lang#103057
bors added a commit to rust-lang-ci/rust that referenced this pull request Apr 16, 2025
… 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 rust-lang#98350 and was not deemed large enough to require additional process.

The tracking issue for this feature is rust-lang#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 rust-lang#98350 by `@pcwalton`
- Stop emitting `.debug_pubnames` and `.debug_pubtypes` when using DWARF 5 in rust-lang#117962 by `@weihanglo.`
- Refactoring & cleanups (rust-lang#135739), fix LLVM warning on LTO with different DWARF versions (rust-lang#136659) and argument validation (rust-lang#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 (rust-lang/cc-rs#1395).

---

Closes rust-lang#103057
github-actions bot pushed a commit to rust-lang/rustc-dev-guide that referenced this pull request Apr 17, 2025
…henkov

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 rust-lang/rust#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 rust-lang/rust#98350 by `@pcwalton`
- Stop emitting `.debug_pubnames` and `.debug_pubtypes` when using DWARF 5 in rust-lang/rust#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 (rust-lang/cc-rs#1395).

---

Closes #103057
github-actions bot pushed a commit to rust-lang/miri that referenced this pull request Apr 17, 2025
…henkov

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 rust-lang/rust#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 rust-lang/rust#98350 by `@pcwalton`
- Stop emitting `.debug_pubnames` and `.debug_pubtypes` when using DWARF 5 in rust-lang/rust#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 (rust-lang/cc-rs#1395).

---

Closes #103057
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.