Stabilize -Zdebuginfo-compression as -Cdebuginfo-compression

[wesleywiser]

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

-Zdebuginfo-compression 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 #115358 and was not deemed large enough to require additional process.

The tracking issue for this feature is #120953.

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

None that has been extensively debated but there is one obvious question:

1. What is the behavior when flag is used on targets that do not support compressed debuginfo?
   Currently, passing -{C,Z} debuginfo-compression on targets like *-windows-msvc does not do anything. I believe it generally makes sense to alert the user when codegen flags are being ignored and I've opened an MCP Lint unsupported, target-specifc codegen flags compiler-team#957 that proposes handling this in a consistent way rather than on a ad-hoc, per-flag basis.

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 not all debuginfo formats support compression (such as PDB/CodeView). If those formats incorporate compression support in the future, this feature can be extended when that support materializes. The implementation does not blindly forward the flag to the linker so we'll need to intentionally modify the compiler to enable that support.

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

• We calculate the effective value of the flag taking into account both -{C,Z} debuginfo-compression (preferring the stabilized -C version)

  rust/compiler/rustc_session/src/session.rs

  Lines 717 to 723 in c419816

  	pub fn debuginfo_compression(&self) -> DebugInfoCompression {
  	self.opts
  	.cg
  	.debuginfo_compression
  	.or(self.opts.unstable_opts.debuginfo_compression)
  	.unwrap_or(DebugInfoCompression::None)
  	}

• The flag is validated in case the LLVM backend build does not support zlib or zstd compression (our LLVM builds include support for both)

  rust/compiler/rustc_codegen_llvm/src/back/write.rs

  Lines 253 to 271 in c419816

  	let debuginfo_compression = match sess.debuginfo_compression() {
  	config::DebugInfoCompression::None => llvm::CompressionKind::None,
  	config::DebugInfoCompression::Zlib => {
  	if llvm::LLVMRustLLVMHasZlibCompression() {
  	llvm::CompressionKind::Zlib
  	} else {
  	sess.dcx().emit_warn(UnknownCompression { algorithm: "zlib" });
  	llvm::CompressionKind::None
  	}
  	}
  	config::DebugInfoCompression::Zstd => {
  	if llvm::LLVMRustLLVMHasZstdCompression() {
  	llvm::CompressionKind::Zstd
  	} else {
  	sess.dcx().emit_warn(UnknownCompression { algorithm: "zstd" });
  	llvm::CompressionKind::None
  	}
  	}
  	};

• When the linker is invoked, we pass along the requested debuginfo compression

  rust/compiler/rustc_codegen_ssa/src/back/linker.rs

  Lines 759 to 767 in c419816

  	match self.sess.debuginfo_compression() {
  	config::DebugInfoCompression::None => {}
  	config::DebugInfoCompression::Zlib => {
  	self.link_arg("--compress-debug-sections=zlib");
  	}
  	config::DebugInfoCompression::Zstd => {
  	self.link_arg("--compress-debug-sections=zstd");
  	}
  	}

The default for the flag is to not request debuginfo compression thus users have to opt-in to any level of compression. Zlib compression is widely supported across many versions of binutils and other tools that read debuginfo like gdb, lldb, perf, etc but zstd compression support is significantly newer and may require using the latest versions of these tools to support it. Users are responsible for ensuring whatever tools they use support the compression algorithm they've requested.

Summarize existing test coverage of this feature

• End-to-end test that we can actually generate compressed debuginfo with both zlib and zstd algorithms
  • https://github.com/rust-lang/rust/tree/c4198169073cfaf1bafe09e850cd5e5132c96a11/tests/run-make/compressed-debuginfo
• End-to-end test that rust-lld can also generate compressed debuginfo with both zlib and zstd algorithms
  • https://github.com/rust-lang/rust/tree/c4198169073cfaf1bafe09e850cd5e5132c96a11/tests/run-make/compressed-debuginfo-zstd

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 debuginfo: add compiler option to allow compressed debuginfo sections #115358 by @durin42
• Zstd support was enabled in our LLVM build in Enable zstd for debug compression. #125642 by @khuey
• Minor cleanups in Cleanup debuginfo_compression unstable flag #150577 by @wesleywiser
• Initial support for zlib compressed debuginfo in the standard library backtrace implementation was added in Handle compressed debug sections in ELF files backtrace-rs#344 by @benesch
• Native support for zlib compressed debuginfo was a motivation for switching the backtrace implementation to gimli in Remove libbacktrace implementation backtrace-rs#423 by @alexcrichton
• Support for zstd compresssed debuginfo was added to the standard library backtrace implementation in Support zstd-compressed ELF sections. backtrace-rs#626 by @khuey

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.

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

No changes to reference/spec, the stable book has documentation added as part of this 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?

None.

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 currently does not.

---

Closes #120953

[rustbot]

r? @fee1-dead

rustbot has assigned @fee1-dead.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[Mark-Simulacrum]

A few questions:

Do we expect both zstd and zlib compression to be available in most distribution LLVM toolchains? Should we consider making that more of a requirement (e.g., needs a flag to opt out of at build time rather than silently not supporting them)? Relatedly, are we confident we ourselves build with support on across all tier 1 and 2 targets? It looks like we require explicit opt-in today for at least zstd, see bootstrap code.

I see in man ld both --compress-debug-sections=zlib-gnu and --compress-debug-sections=zlib-gabi ("--compress-debug-sections=none doesn't compress DWARF debug sections. --compress-debug-sections=zlib-gnu compresses DWARF debug sections and renames them to begin with .zdebug instead of .debug. --compress-debug-sections=zlib-gabi also compresses DWARF debug sections, but rather than renaming them it sets the SHF_COMPRESSED flag in the sections' headers."). Are we using gnu or gabi? Should we support both?

It also looks like =none for ld at least is not the same as nothing, it'll actively decompress sections that are from upstream sources ("Note that this option overrides any compression in input debug sections, so if a binary is linked with --compress-debug-sections=none for example, then any compressed debug sections in input files will be uncompressed before they are copied into the output binary."). Do we want an explicit =none option of our own that's distinct from "do nothing, i.e., leave sections as-is", if that's a reasonable position to take?

[khuey]

Support for zstd compresssed debuginfo was added to the standard library backtrace implementation in rust-lang/backtrace-rs#626 by @khuey

Unfortunately while backtrace-rs has support for zstd compressed debug info it was never turned on in std due to binary size concerns. See #130417

[bjorn3]

What happens when LLVM is compiled without zlib or zstd support? Do we error, silently not compress or not compress with a warning?

[Mark-Simulacrum]

One other thought: in principle, compression implies additional parameters (at least a level). We should consider how/if we would want to expose that via some standard flag. It looks like lld exposes raising the level via -O2, which will use level 6 compression rather than 1 per the man page I have...

[fee1-dead]

@rustbot reroll