mirror
/
rustc-dev-guide
mirror of https://github.com/rust-lang/rustc-dev-guide.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
A guide to how rustc works and how to contribute to it.
3,473 Commits 3 Branches 0 Tags 114 MiB
Rust 89.3%
Shell 10.5%
JavaScript 0.2%
Go to file
bors 94acf3cfdc 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: 34a5ea911c/compiler/rustc_target/src/spec/mod.rs (L2369)
- We use the target default but this can be overriden by `-{C,Z} dwarf-version` 34a5ea911c/compiler/rustc_session/src/session.rs (L738)
- The flag is validated 34a5ea911c/compiler/rustc_session/src/session.rs (L1253-L1258)
- When debuginfo is generated, we tell LLVM to use the requested value or the target default 34a5ea911c/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](34a5ea911c/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
 		2025-04-16 06:38:00 +00:00
.github/workflows Set linkcheck in `ci.yml` 2025-03-19 17:25:07 +08:00
ci add rustfmt settings file 2025-03-30 00:31:44 +02:00
examples add rustfmt settings file 2025-03-30 00:31:44 +02:00
josh-sync Distinguish between "nothing to pull" and "pull error" in josh-sync 2025-01-30 16:48:39 +01:00
src Documentation fixes. 2025-04-14 09:18:15 +10:00
.editorconfig Set max line length in `.editorconfig` to 100 (#1788) 2023-09-05 23:24:59 +09:00
.gitattributes .gitattributes: Mark minified javascript as binary to filter greps 2022-10-07 18:34:51 +02:00
.gitignore add josh-sync build dir to gitignore (#2196) 2025-01-06 02:57:03 +08:00
.mailmap add a mailmap 2023-12-17 18:21:38 +01:00
CITATION.cff Add a citation file 2023-02-11 08:41:56 +02:00
CNAME cname (#606) 2020-03-09 18:10:52 -03:00
CODE_OF_CONDUCT.md Fix some links (#1865) 2024-01-28 19:44:41 -03:00
LICENSE-APACHE add code-of-conduct, licensing material, and a README 2018-01-16 16:36:21 -05:00
LICENSE-MIT add code-of-conduct, licensing material, and a README 2018-01-16 16:36:21 -05:00
README.md Document `fetch.prunetags = true` gotcha during rustc-pull 2025-03-13 15:44:23 +08:00
book.toml Update book.toml fix the authors field 2025-04-04 08:34:08 +03:00
mermaid-init.js add mdbook-mermaid 2022-07-17 23:34:12 +02:00
mermaid.min.js add mdbook-mermaid 2022-07-17 23:34:12 +02:00
rust-version Preparing for merge from rustc 2025-04-07 04:06:33 +00:00
rustfmt.toml add rustfmt settings file 2025-03-30 00:31:44 +02:00
triagebot.toml Add CI workflow for performing rustc-pull 2025-01-11 17:50:07 +01:00

README.md

CI

This is a collaborative effort to build a guide that explains how rustc works. The aim of the guide is to help new contributors get oriented to rustc, as well as to help more experienced folks in figuring out some new part of the compiler that they haven't worked on before.

You can read the latest version of the guide here.

You may also find the rustdocs for the compiler itself useful. Note that these are not intended as a guide; it's recommended that you search for the docs you're looking for instead of reading them top to bottom.

For documentation on developing the standard library, see std-dev-guide.

Contributing to the guide

The guide is useful today, but it has a lot of work still to go.

If you'd like to help improve the guide, we'd love to have you! You can find plenty of issues on the issue tracker. Just post a comment on the issue you would like to work on to make sure that we don't accidentally duplicate work. If you think something is missing, please open an issue about it!

In general, if you don't know how the compiler works, that is not a problem! In that case, what we will do is to schedule a bit of time for you to talk with someone who does know the code, or who wants to pair with you and figure it out. Then you can work on writing up what you learned.

In general, when writing about a particular part of the compiler's code, we recommend that you link to the relevant parts of the rustc rustdocs.

Build Instructions

To build a local static HTML site, install mdbook with:

> cargo install mdbook mdbook-linkcheck2 mdbook-toc mdbook-mermaid

and execute the following command in the root of the repository:

> mdbook build --open

The build files are found in the book/html directory.

Link Validations

We use mdbook-linkcheck2 to validate URLs included in our documentation. Link checking is not run by default locally, though it is in CI. To enable it locally, set the environment variable ENABLE_LINKCHECK=1 like in the following example.

$ ENABLE_LINKCHECK=1 mdbook serve

Table of Contents

We use mdbook-toc to auto-generate TOCs for long sections. You can invoke the preprocessor by including the <!-- toc --> marker at the place where you want the TOC.

Synchronizing josh subtree with rustc

This repository is linked to rust-lang/rust as a josh subtree. You can use the following commands to synchronize the subtree in both directions.

You'll need to install josh-proxy locally via

cargo +stable install josh-proxy --git https://github.com/josh-project/josh --tag r24.10.04

Older versions of josh-proxy may not round trip commits losslessly so it is important to install this exact version.

Pull changes from rust-lang/rust into this repository

  1. Checkout a new branch that will be used to create a PR into rust-lang/rustc-dev-guide
  2. Run the pull command 
    $ cargo run --manifest-path josh-sync/Cargo.toml rustc-pull
  3. Push the branch to your fork and create a PR into rustc-dev-guide

Push changes from this repository into rust-lang/rust

  1. Run the push command to create a branch named <branch-name> in a rustc fork under the <gh-username> account 
    $ cargo run --manifest-path josh-sync/Cargo.toml rustc-push <branch-name> <gh-username>
  2. Create a PR from <branch-name> into rust-lang/rust

Minimal git config

For simplicity (ease of implementation purposes), the josh-sync script simply calls out to system git. This means that the git invocation may be influenced by global (or local) git configuration.

You may observe "Nothing to pull" even if you know rustc-pull has something to pull if your global git config sets fetch.prunetags = true (and possibly other configurations may cause unexpected outcomes).

To minimize the likelihood of this happening, you may wish to keep a separate minimal git config that only has [user] entries from global git config, then repoint system git to use the minimal git config instead. E.g.

$ GIT_CONFIG_GLOBAL=/path/to/minimal/gitconfig GIT_CONFIG_SYSTEM='' cargo +stable run --manifest-path josh-sync/Cargo.toml -- rustc-pull