rust Documentation

Technical Documentation: rust-lang/rust

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

This is the main source code repository for Rust. It contains the compiler,
standard library, and documentation.

Why Rust? Copy Chapter

• Performance: Fast and memory-efficient, suitable for critical services, embedded devices, and easily integrated with other languages.

• Reliability: Our rich type system and ownership model ensure memory and thread safety, reducing bugs at compile-time.

• Productivity: Comprehensive documentation, a compiler committed to providing great diagnostics, and advanced tooling including package manager and build tool (Cargo), auto-formatter (rustfmt), linter (Clippy) and editor support (rust-analyzer).

Quick Start Copy Chapter

Read "Installation" from The Book.

Installing from Source Copy Chapter

If you really want to install from source (though this is not recommended), see
INSTALL.md.

Getting Help Copy Chapter

See https://www.rust-lang.org/community for a list of chat platforms and forums.

Contributing Copy Chapter

See CONTRIBUTING.md.

For a detailed explanation of the compiler's architecture and how to begin contributing, see the rustc-dev-guide.

License Copy Chapter

Rust is primarily distributed under the terms of both the MIT license and the
Apache License (Version 2.0), with portions covered by various BSD-like
licenses.

See LICENSE-APACHE, LICENSE-MIT, and
COPYRIGHT for details.

Trademark Copy Chapter

The Rust Foundation owns and protects the Rust and Cargo
trademarks and logos (the "Rust Trademarks").

If you want to use these names or brands, please read the
Rust language trademark policy.

Third-party logos may be subject to third-party copyrights and trademarks. See
Licenses for details.

Src Doc Index (`src/doc/index.md`) Copy Section

% Rust Documentation

Welcome to an overview of the documentation provided by the Rust
project. This page contains links to various helpful references,
most of which are available offline (if opened with rustup doc). Many of these
resources take the form of "books"; we collectively call these "The Rust
Bookshelf." Some are large, some are small.

All of these books are managed by the Rust Organization, but other unofficial
documentation resources are included here as well!

If you're just looking for the standard library reference, here it is:
Rust API documentation

Learning Rust Copy Chapter

If you'd like to learn Rust, this is the section for you! All of these resources
assume that you have programmed before, but not in any specific language:

The Rust Programming Language Copy Section

Affectionately nicknamed "the book," The Rust Programming Language
will give you an overview of the language from first principles. You'll build a
few projects along the way, and by the end, you'll have a solid grasp of how to
use the language.

Rust By Example Copy Section

If reading multiple hundreds of pages about a language isn't your style, then
Rust By Example has you covered. RBE shows off a
bunch of code without using a lot of words. It also includes exercises!

Rustlings Copy Section

Rustlings guides you
through downloading and setting up the Rust toolchain, then provides an
interactive tool that teaches you how to solve coding challenges in Rust.

Rust Playground Copy Section

The Rust Playground is a great place
to try out and share small bits of code, or experiment with some of the most
popular crates.

Using Rust Copy Chapter

Once you've gotten familiar with the language, these resources can help you put
it to work.

The Standard Library Copy Section

Rust's standard library has extensive API documentation, with
explanations of how to use various things, as well as example code for
accomplishing various tasks. Code examples have a "Run" button on hover that
opens the sample in the playground.

Search

Your Personal Documentation Copy Section

Whenever you are working in a crate, cargo doc --open will generate
documentation for your project and all its dependencies in their correct
version, and open it in your browser. Add the flag --document-private-items to
also show items not marked pub.

Rust Version History Copy Section

The Release Notes describes the change history of the Rust
toolchain and language.

The Edition Guide describes the Rust editions and
their differences. The latest version of the toolchain supports all
historical editions.

The `rustc` Book Copy Section

The rustc Book describes the Rust compiler, rustc.

The Cargo Book Copy Section

The Cargo Book is a guide to Cargo, Rust's build tool and
dependency manager.

The Rustdoc Book Copy Section

The Rustdoc Book describes our documentation tool, rustdoc.

The Clippy Book Copy Section

The Clippy Book describes our static analyzer, Clippy.

Extended Error Listing Copy Section

Many of Rust's errors come with error codes, and you can request extended
diagnostics from the compiler on those errors (with rustc --explain). You can
also read them here if you prefer: rustc error codes

Mastering Rust Copy Chapter

Once you're quite familiar with the language, you may find these advanced
resources useful.

The Reference Copy Section

The Reference is not a formal spec, but is more detailed
and comprehensive than the book.

The Style Guide Copy Section

The Rust Style Guide describes the standard formatting
of Rust code. Most developers use cargo fmt to invoke rustfmt and format the
code automatically (the result matches this style guide).

The Rustonomicon Copy Section

The Rustonomicon is your guidebook to the dark arts of
unsafe Rust. It's also sometimes called "the 'nomicon."

The Unstable Book Copy Section

The Unstable Book has documentation for unstable
features.

The `rustc` Development Guide Copy Section

The rustc-dev-guide
documents how the compiler works and how to contribute to it. This is useful if
you want to build or modify the Rust compiler from source (e.g. to target
something non-standard).

Specialized Rust Copy Chapter

When using Rust in specific domains, consider using the following resources
tailored to each area.

Embedded Systems Copy Section

When developing for Bare Metal or Embedded Linux systems, you may find these
resources maintained by the Embedded Working Group useful.

The Embedded Rust Book

The Embedded Rust Book is targeted at developers who are familiar with embedded
development and Rust, but who have not used Rust for embedded development.

Src Doc Intro (`src/doc/intro.md`) Copy Section

% A 30-minute Introduction to Rust

This introduction is now deprecated. Please see the introduction to the book.

Src Doc Rustc Dev Guide README (`src/doc/rustc-dev-guide/README.md`) Copy Section

About the `rustc-dev-guide` Copy Chapter

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.

For more information, see About This Guide.

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

Contributing to the guide Copy Chapter

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!

See below for instructions on writing new docs.

The guide has a much lower bar for what it takes for a PR to be merged.
Check out the forge documentation for our policy.

Build Instructions Copy Chapter

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

cargo install --locked mdbook mdbook-linkcheck2 mdbook-mermaid

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

mdbook serve --open

For a one-off build, you can use mdbook build.

Link Validations Copy Section

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

Editing the guide Copy Chapter

Where to start Copy Section

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.

Layout Copy Section

The dev-guide is organized as a normal mdBook:
It has a src/SUMMARY.md table of contents, which links to individual pages under src/.
Configuration lives in book.toml.
Images are in src/img.
The build files are found in the book/html directory.

NOTE: if you do not add a page to SUMMARY.md, it will not be shown!

While writing Copy Section

See the guide itself for instructions on writing new docs.

Maintaining the guide Copy Chapter

CI Copy Section

Various tools are kept under ci/.
Check links with mdbook-linkcheck2 --standalone.
Check semantic line breaks with cargo run --manifest-path ci/sembr/Cargo.toml src.
Triage `` annotations with cargo run --manifest-path ci/date-check/Cargo.toml ..

You can test those tools with cargo test --manifest-path ci/<tool>/Cargo.toml.

Synchronizing josh subtree with rustc Copy Section

This repository is linked to rust-lang/rust as a josh subtree.
You can use the rustc-josh-sync tool to perform synchronization.

You can find a guide on how to perform the synchronization here.

Src Doc Rustdoc README (`src/doc/rustdoc/README.md`) Copy Section

Rustdoc

This is documentation for rustdoc itself, written in mdbook format.
To build the book, use x.py doc src/doc/rustdoc.
To run doctests, use x.py test src/doc/rustdoc.

Src Doc Unstable Book README (`src/doc/unstable-book/README.md`) Copy Section

Unstable Book

These are the sources for https://doc.rust-lang.org/nightly/unstable-book/.
To generate them, run ./x doc unstable-book, which will generate HTML files in build/host/doc/unstable-book using src/tools/rustbook.
If you need to change the overall structure, modify src/tools/unstable-book-gen/src/SUMMARY.md.

Note that most of this book is autogenerated by unstable-book-gen, with the exception of compiler-flags and compiler-environment-variables.
As a result, it does not integrate well with mdbook. Use ./x doc instead.

Src Doc Rustc Dev Guide Src Getting Started (`src/doc/rustc-dev-guide/src/getting-started.md`) Copy Section

Getting Started

Thank you for your interest in contributing to Rust!
There are many ways to contribute, and we appreciate all of them.

For general information about how to contribute to Rust,
see Forge.
The rest of this section is about how to contribute to the compiler specifically.

This documentation is not intended to be comprehensive;
it is meant to be a quick guide for the most useful things.
For more information,
see How to build and run the compiler.

Finding help Copy Chapter

See also "Asking
Questions".

Experts Copy Section

Not all t-compiler members are experts on all parts of rustc;
it's a pretty large project.
To find out who could have some expertise on
different parts of the compiler, consult triagebot assign groups.
The sections that start with [assign* in triagebot.toml file.
But also, feel free to ask questions even if you can't figure out who to ping.

Another way to find experts for a given part of the compiler is to see who has made recent commits.
For example, to find people who have recently worked on name resolution since the 1.68.2 release,
you could run git shortlog -n 1.68.2.. compiler/rustc_resolve/.
Ignore any commits starting with
"Rollup merge" or commits by @bors (see CI contribution procedures for
more information about these commits).

What should I work on? Copy Chapter

The rust monorepo is quite large and it can be difficult to know which parts need
help, or are a good starting place for beginners.
Here are some suggested starting places.

Easy or mentored issues Copy Section

If you're looking for somewhere to start, check out the following issue
search.
See the Triage for an explanation of these labels.
You can also try filtering the search to areas you're interested in.
For example:

• label:T-compiler will only show issues related to the compiler
• label:A-diagnostics will only show diagnostic issues

Not all important or beginner work has issue labels.
See below for how to find work that isn't labelled.

Recurring work Copy Section

Some work is too large to be done by a single person.
In this case, it's common to have "Tracking issues" to co-ordinate the work between contributors.
Here are some example tracking issues where
it's easy to pick up work without a large time commitment:

• Add recurring work items here.

If you find more recurring work, please feel free to add it here!

Diagnostic issues Copy Section

Many diagnostic issues are self-contained and don't need detailed background knowledge of the
compiler.
You can see a list of diagnostic issues here.

Picking up abandoned pull requests Copy Section

Sometimes, contributors send a pull request, but later find out that they don't have enough
time to work on it, or they simply are not interested in it anymore.
Such PRs are often eventually closed and they receive the S-inactive label.
You could try to examine some of these PRs and pick up the work.
You can find the list of such PRs here.

If the PR has been implemented in some other way in the meantime, the S-inactive label
should be removed from it.
If not, and it seems that there is still interest in the change,
you can try to rebase the pull request on top of the latest main branch and send a new
pull request, continuing the work on the feature.

Writing tests Copy Section

Issues that have been resolved but do not have a regression test are marked with the E-needs-test label.
Writing unit tests is a low-risk,
lower-priority task that offers new contributors a great opportunity to familiarize themselves
with the testing infrastructure and contribution workflow.
You can see a list of needs test issues here.

Contributing to std (standard library) Copy Section

See std-dev-guide.

Other ways to contribute Copy Section

See Forge.

Cloning and Building Copy Chapter

See "How to build and run the compiler".

Bug fixes or "normal" code changes Copy Chapter

For most PRs, no special procedures are needed.
You can just open a PR, and it will be reviewed, approved, and merged.
This includes most bug fixes, refactorings, and other user-invisible changes.
The next few sections talk about exceptions to this rule.

Also, note that it is perfectly acceptable to open WIP PRs or GitHub Draft PRs.
Some people prefer to do this so they can get feedback along the
way or share their code with a collaborator.
Others do this so they can utilize
the CI to build and test their PR (e.g. when developing on a slow machine).

Pull requests Copy Chapter

Pull requests (or PRs for short) are the primary mechanism we use to change Rust.
GitHub itself has some great documentation on using the Pull Request feature.
We use the "fork and pull" model,
where contributors push changes to their personal fork and create pull requests to
bring those changes into the source repository.
We have a chapter on how to use Git when contributing to Rust.

Advice for potentially large, complex, cross-cutting and/or very domain-specific changes

The compiler reviewers on rotation usually each have areas of the compiler that they know well,
but also have areas that they are not very familiar with. If your PR contains changes that are
large, complex, cross-cutting and/or highly domain-specific, it becomes very difficult to find a
suitable reviewer who is comfortable in reviewing all of the changes in such a PR. This is also
true if the changes are not only compiler-specific but also contain changes which fall under the
purview of reviewers from other teams, like the standard library team. There's a bot
which notifies the relevant teams and pings people who have set up specific alerts based on the
files modified.

Before making such changes, you are strongly encouraged to discuss your proposed changes with
the compiler team beforehand (and with other teams that the changes would require approval
from), and work with the compiler team to see if we can help you break down a large potentially
unreviewable PR into a series of smaller more individually reviewable PRs.

You can communicate with the compiler team by creating a #t-compiler thread on Zulip
to discuss your proposed changes.

Communicating with the compiler team beforehand helps in several ways:

1. It increases the likelihood of your PRs being reviewed in a timely manner.
   • We can help you identify suitable reviewers before you open actual PRs, or help find
     advisors and liaisons to help you navigate the change procedures, or help with running
     try-jobs, perf runs and crater runs as suitable.
2. It helps the compiler team track your changes.
3. The compiler team can perform vibe checks on your changes early and often, to see if the
   direction of the changes align with what the compiler team prefers to see.
4. Helps to avoid situations where you may have invested significant time and effort into large
   changes that the compiler team might not be willing to accept, or finding out very late that the
   changes are in a direction that the compiler team disagrees with.

Issue triage Copy Chapter

Please see https://forge.rust-lang.org/release/issue-triaging.html.

Other Resources Copy Chapter

This section has moved to the "About this guide" chapter.

Src Doc Rustc Dev Guide Src Overview (`src/doc/rustc-dev-guide/src/overview.md`) Copy Section

Overview of the compiler

This chapter is about the overall process of compiling a program -- how everything fits together.

The Rust compiler is special in two ways: it does things to your code that
other compilers don't do (e.g. borrow-checking) and it has a lot of
unconventional implementation choices (e.g. queries).
We will talk about these in turn in this chapter, and in the rest of the guide, we will look at the
individual pieces in more detail.

What the compiler does to your code Copy Chapter

So first, let's look at what the compiler does to your code.
For now, we will avoid mentioning how the compiler implements these steps except as needed.

Invocation Copy Section

Compilation begins when a user writes a Rust source program in text and invokes
the rustc compiler on it.
The work that the compiler needs to perform is defined by command-line options.
For example, it is possible to enable nightly
features (-Z flags), perform check-only builds, or emit the LLVM
Intermediate Representation (LLVM-IR) rather than executable machine code.
The rustc executable call may be indirect through the use of cargo.

Command line argument parsing occurs in the rustc_driver.
This crate defines the compile configuration that is requested by the user and passes it
to the rest of the compilation process as a rustc_interface::Config.

Lexing and parsing Copy Section

The raw Rust source text is analyzed by a low-level lexer located in rustc_lexer.
At this stage, the source text is turned into a stream of
atomic source code units known as tokens.
The lexer supports the Unicode character encoding.

The token stream passes through a higher-level lexer located in
rustc_parse to prepare for the next stage of the compile process.
The Lexer struct is used at this stage to perform a set of validations
and turn strings into interned symbols (interning is discussed later).
String interning is a way of storing only one immutable copy of each distinct string value.

The lexer has a small interface and doesn't depend directly on the diagnostic
infrastructure in rustc.
Instead it provides diagnostics as plain data which
are emitted in rustc_parse::lexer as real diagnostics.
The lexer preserves full fidelity information for both IDEs and procedural macros
(sometimes referred to as "proc-macros").

The parser translates the token stream from the lexer into an Abstract Syntax
Tree (AST).
It uses a recursive descent (top-down) approach to syntax analysis.
The crate entry points for the parser are the
Parser::parse_crate_mod and Parser::parse_mod
methods found in rustc_parse::parser::Parser.
The external module parsing
entry point is rustc_expand::module::parse_external_mod.
And the macro-parser entry point is Parser::parse_nonterminal.

Parsing is performed with a set of parser utility methods including bump,
check, eat, expect, look_ahead.

Parsing is organized by semantic construct.
Separate parse_* methods can be found in the rustc_parse directory.
The source file name follows the construct name.
For example, the following files are found in the parser:

• expr.rs
• pat.rs
• ty.rs
• stmt.rs

This naming scheme is used across many compiler stages.
You will find either a file or directory with the same name across the parsing, lowering, type
checking, Typed High-level Intermediate Representation (THIR) lowering, and
Mid-level Intermediate Representation (MIR) building sources.

Macro-expansion, AST-validation, name-resolution, and early linting also take
place during the lexing and parsing stage.

The rustc_ast::ast::{Crate, Expr, Pat, ...} AST nodes are
returned from the parser while the standard Diag API is used for error handling.
Generally Rust's compiler will try to recover from errors
by parsing a superset of Rust's grammar, while also emitting an error type.

`AST` lowering Copy Section

Next the AST is converted into High-Level Intermediate Representation
(HIR), a more compiler-friendly representation of the AST.
This process is called "lowering" and involves a lot of desugaring (the expansion and
formalizing of shortened or abbreviated syntax constructs) of things like loops and async fn.

We then use the HIR to do type inference (the process of automatic
detection of the type of an expression), trait solving (the process of
pairing up an impl with each reference to a trait), and type checking.
Type checking is the process of converting the types found in the HIR (hir::Ty),
which represent what the user wrote, into the internal representation used by
the compiler (Ty<'tcx>).
It's called type checking because the information
is used to verify the type safety, correctness and coherence of the types used in the program.

`MIR` lowering Copy Section

The HIR is further lowered to MIR
(used for borrow checking) by constructing the THIR (an even more desugared HIR used for
pattern and exhaustiveness checking) to convert into MIR.

We do many optimizations on the MIR because it is generic and that
improves later code generation and compilation speed.
It is easier to do some optimizations at MIR level than at LLVM-IR level.
For example LLVM doesn't seem
to be able to optimize the pattern the simplify_try MIR-opt looks for.

Rust code is also monomorphized during code generation, which means making
copies of all the generic code with the type parameters replaced by concrete types.
To do this, we need to collect a list of what concrete types to generate code for.
This is called monomorphization collection and it happens at the MIR level.

Code generation Copy Section

We then begin what is simply called code generation or codegen.
The code generation stage is when higher-level representations of source are
turned into an executable binary.
Since rustc uses LLVM for code generation,
the first step is to convert the MIR to LLVM-IR.
This is where the MIR is actually monomorphized.
The LLVM-IR is passed to LLVM, which does a lot more
optimizations on it, emitting machine code which is basically assembly code
with additional low-level types and annotations added (e.g. an ELF object or
WASM).
The different libraries/binaries are then linked together to produce the final binary.

How it does it Copy Chapter

Now that we have a high-level view of what the compiler does to your code,
let's take a high-level view of how it does all that stuff.
There are a lot of constraints and conflicting goals that the compiler needs to
satisfy/optimize for.
For example,

• Compilation speed: how fast is it to compile a program?
  More/better compile-time analyses often means compilation is slower.
  • Also, we want to support incremental compilation, so we need to take that into account.
    How can we keep track of what work needs to be redone and
    what can be reused if the user modifies their program?
    • Also we can't store too much stuff in the incremental cache because
      it would take a long time to load from disk and it could take a lot
      of space on the user's system...
• Compiler memory usage: while compiling a program, we don't want to use more memory than we need.
• Program speed: how fast is your compiled program?
  More/better compile-time analyses often means the compiler can do better optimizations.
• Program size: how large is the compiled binary?
  Similar to the previous point.
• Compiler compilation speed: how long does it take to compile the compiler?
  This impacts contributors and compiler maintenance.
• Implementation complexity: building a compiler is one of the hardest
  things a person/group can do, and Rust is not a very simple language, so how
  do we make the compiler's code base manageable?
• Compiler correctness: the binaries produced by the compiler should do what
  the input programs says they do, and should continue to do so despite the
  tremendous amount of change constantly going on.
• Integration: a number of other tools need to use the compiler in
  various ways (e.g. cargo, clippy, Miri) that must be supported.
• Compiler stability: the compiler should not crash or fail ungracefully on the stable channel.
• Rust stability: the compiler must respect Rust's stability guarantees by not
  breaking programs that previously compiled despite the many changes that are
  always going on to its implementation.
• Limitations of other tools: rustc uses LLVM in its backend, and LLVM has some
  strengths we leverage and some aspects we need to work around.

So, as you continue your journey through the rest of the guide, keep these things in mind.
They will often inform decisions that we make.

Intermediate representations Copy Section

As with most compilers, rustc uses some intermediate representations (IRs) to
facilitate computations.
In general, working directly with the source code is extremely inconvenient and error-prone.
Source code is designed to be human-friendly while at
the same time being unambiguous, but it's less convenient for doing something
like, say, type checking.

Instead most compilers, including rustc, build some sort of IR out of the
source code which is easier to analyze.
rustc has a few IRs, each optimized for different purposes:

• Token stream: the lexer produces a stream of tokens directly from the source code.
  This stream of tokens is easier for the parser to deal with than raw text.
• Abstract Syntax Tree (AST): the abstract syntax tree is built from the stream
  of tokens produced by the lexer.
  It represents pretty much exactly what the user wrote.
  It helps to do some syntactic sanity
  checking (e.g. checking that a type is expected where the user wrote one).
• High-level IR (HIR): This is a sort of desugared AST.
  It's still close to what the user wrote syntactically, but it includes some implicit things
  such as some elided lifetimes, etc. This IR is amenable to type checking.
• Typed HIR (THIR) formerly High-level Abstract IR (HAIR): This is an
  intermediate between HIR and MIR.
  It is like the HIR but it is fully typed
  and a bit more desugared (e.g. method calls and implicit dereferences are
  made fully explicit).
  As a result, it is easier to lower to MIR from THIR than from HIR.
• Middle-level IR (MIR): This IR is basically a Control-Flow Graph (CFG).
  A CFG is a type of diagram that shows the basic blocks of a program and how control
  flow can go between them.
  Likewise, MIR also has a bunch of basic blocks with
  simple typed statements inside them (e.g. assignment, simple computations,
  etc) and control flow edges to other basic blocks (e.g., calls, dropping
  values).
  MIR is used for borrow checking and other
  important dataflow-based checks, such as checking for uninitialized values.
  It is also used for a series of optimizations and for constant evaluation (via Miri).
  Because MIR is still generic, we can do a lot of analyses here more
  efficiently than after monomorphization.
• LLVM-IR: This is the standard form of all input to the LLVM compiler.
  LLVM-IR is a sort of typed assembly language with lots of annotations.
  It's
  a standard format that is used by all compilers that use LLVM (e.g. the clang
  C compiler also outputs LLVM-IR).
  LLVM-IR is designed to be easy for other
  compilers to emit and also rich enough for LLVM to run a bunch of optimizations on it.

One other thing to note is that many values in the compiler are interned.
This is a performance and memory optimization in which we allocate the values in
a special allocator called an arena.
Then, we pass around references to the values allocated in the arena.
This allows us to make
sure that identical values (e.g. types in your program) are only allocated once
and can be compared cheaply by comparing pointers.
Many of the intermediate representations are interned.

Queries Copy Section

The first big implementation choice is Rust's use of the query system in its compiler.
The Rust compiler is not organized as a series of passes over the code which execute sequentially.
The Rust compiler does this to make
incremental compilation possible -- that is, if the user makes a change to
their program and recompiles, we want to do as little redundant work as
possible to output the new binary.

In rustc, all the major steps above are organized as a bunch of queries that call each other.
For example, there is a query to ask for the type of something
and another to ask for the optimized MIR of a function.
These queries can call each other and are all tracked through the query system.
The results of the queries are cached on disk so that the compiler can tell which queries' results
changed from the last compilation and only redo those.
This is how incremental compilation works.

In principle, for the query-fied steps, we do each of the above for each item individually.
For example, we will take the HIR for a function and use queries
to ask for the LLVM-IR for that HIR.
This drives the generation of optimized
MIR, which drives the borrow checker, which drives the generation of MIR, and so on.

... except that this is very over-simplified.
In fact, some queries are not
cached on disk, and some parts of the compiler have to run for all code anyway
for correctness even if the code is dead code (e.g. the borrow checker). For
example, currently the mir_borrowck query is first executed on all functions
of a crate. Then the codegen backend invokes the
collect_and_partition_mono_items query, which first recursively requests the
optimized_mir for all reachable functions, which in turn runs mir_borrowck
for that function and then creates codegen units.
This kind of split will need
to remain to ensure that unreachable functions still have their errors emitted.

Moreover, the compiler wasn't originally built to use a query system; the query
system has been retrofitted into the compiler, so parts of it are not query-fied yet.
Also, LLVM isn't our code, so that isn't querified either.
The plan is to eventually query-fy all of the steps listed in the previous section,
but as of November 2022, only the steps between HIR and
LLVM-IR are query-fied.
That is, lexing, parsing, name resolution, and macro
expansion are done all at once for the whole program.

One other thing to mention here is the all-important "typing context",
TyCtxt, which is a giant struct that is at the center of all things.
(Note that the name is mostly historic.
This is not a "typing context" in the sense of Γ or Δ from type theory.
The name is retained because that's what the name of the struct is in the source code.) All
queries are defined as methods on the TyCtxt type, and the in-memory query
cache is stored there too.
In the code, there is usually a variable called tcx which is a handle on the typing context.
You will also see lifetimes with
the name 'tcx, which means that something is tied to the lifetime of the
TyCtxt (usually it is stored or interned there).

For more information about queries in the compiler, see the queries chapter.

`ty::Ty` Copy Section

Types are really important in Rust, and they form the core of a lot of compiler analyses.
The main type (in the compiler) that represents types (in the user's
program) is rustc_middle::ty::Ty.
This is so important that we have a whole chapter
on ty::Ty, but for now, we just want to mention that it exists and is the way
rustc represents types!

Also note that the rustc_middle::ty module defines the TyCtxt struct we mentioned before.

Parallelism Copy Section

Compiler performance is a problem that we would like to improve on (and are always working on).
One aspect of that is parallelizing rustc itself.

Currently, there is only one part of rustc that is parallel by default:
code generation.

However, the rest of the compiler is still not yet parallel.
There have been lots of efforts spent on this, but it is generally a hard problem.
The current approach is to turn RefCells into Mutexs -- that is, we
switch to thread-safe internal mutability.
However, there are ongoing
challenges with lock contention, maintaining query-system invariants under
concurrency, and the complexity of the code base.
One can try out the current work by enabling parallel compilation in bootstrap.toml.
It's still early days,
but there are already some promising performance improvements.

Bootstrapping Copy Section

rustc itself is written in Rust.
So how do we compile the compiler? We use an older compiler to compile the newer compiler.
This is called bootstrapping.

Bootstrapping has a lot of interesting implications.
For example, it means that one of the major users of Rust is the Rust compiler, so we are
constantly testing our own software ("eating our own dogfood").

For more details on bootstrapping, see the bootstrapping section of the guide.

References

• Command line parsing
  • Guide: The Rustc Driver and Interface
  • Driver definition: rustc_driver
  • Main entry point: rustc_session::config::build_session_options
• Lexical Analysis: Lex the user program to a stream of tokens
  • Guide: Lexing and Parsing
  • Lexer definition: rustc_lexer
  • Main entry point: rustc_lexer::Cursor::advance_token
• Parsing: Parse the stream of tokens to an Abstract Syntax Tree (AST)
  • Guide: Lexing and Parsing
  • Guide: Macro Expansion
  • Guide: Name Resolution
  • Parser definition: rustc_parse
  • Main entry points:
    • Entry point for first file in crate
    • Entry point for outline module parsing
    • Entry point for macro fragments
  • AST definition: rustc_ast
  • Feature gating: Feature Gate Checking
  • Early linting: TODO
• The High Level Intermediate Representation (HIR)
  • Guide: The HIR
  • Guide: Identifiers in the HIR
  • Guide: The HIR Map
  • Guide: Lowering AST to HIR
  • How to view HIR representation for your code cargo rustc -- -Z unpretty=hir-tree
  • Rustc HIR definition: rustc_hir
  • Main entry point: TODO
  • Late linting: TODO
• Type Inference
  • Guide: Type Inference
  • Guide: The ty Module: Representing Types (semantics)
  • Main entry point (type inference): InferCtxtBuilder::enter
  • Main entry point (type checking bodies): the typeck query
    • These two functions can't be decoupled.
• The Mid Level Intermediate Representation (MIR)
  • Guide: The MIR (Mid level IR)
  • Definition: rustc_middle/src/mir
  • Definition of sources that manipulates the MIR: rustc_mir_build, rustc_mir_dataflow, rustc_mir_transform
• The Borrow Checker
  • Guide: MIR Borrow Check
  • Definition: rustc_borrowck
  • Main entry point: mir_borrowck query
• MIR Optimizations
  • Guide: MIR Optimizations
  • Definition: rustc_mir_transform
  • Main entry point: optimized_mir query
• Code Generation
  • Guide: Code Generation
  • Generating Machine Code from LLVM-IR with LLVM - TODO: reference?
  • Main entry point: rustc_codegen_ssa::base::codegen_crate
    • This monomorphizes and produces LLVM-IR for one codegen unit.
      It then starts a background thread to run LLVM, which must be joined later.
    • Monomorphization happens lazily via FunctionCx::monomorphize and rustc_codegen_ssa::base::codegen_instance

Src Doc Rustc Dev Guide Src Part 2 Intro (`src/doc/rustc-dev-guide/src/part-2-intro.md`) Copy Section

High-Level Compiler Architecture

The remaining parts of this guide discuss how the compiler works. They go
through everything from high-level structure of the compiler to how each stage
of compilation works. They should be friendly to both readers interested in the
end-to-end process of compilation and readers interested in learning about a
specific system they wish to contribute to. If anything is unclear, feel free
to file an issue on the rustc-dev-guide
repo or contact the compiler
team, as detailed in this chapter from Part 1.

In this part, we will look at the high-level architecture of the compiler. In
particular, we will look at three overarching design choices that impact the
whole compiler: the query system, incremental compilation, and interning.

Src Doc Rustc Dev Guide Src Part 3 Intro (`src/doc/rustc-dev-guide/src/part-3-intro.md`) Copy Section

Source Code Representation

This part describes the process of taking raw source code from the user and
transforming it into various forms that the compiler can work with easily.
These are called intermediate representations (IRs).

This process starts with compiler understanding what the user has asked for:
parsing the command line arguments given and determining what it is to compile.
After that, the compiler transforms the user input into a series of IRs that
look progressively less like what the user wrote.

Src Doc Rustc Dev Guide Src Part 4 Intro (`src/doc/rustc-dev-guide/src/part-4-intro.md`) Copy Section

Analysis

This part discusses the many analyses that the compiler uses to check various
properties of the code and to inform later stages.
Typically, this is what people mean when they talk about "Rust's type system".
This includes the representation, inference, and checking of types, the trait system, and the
borrow checker.
These analyses do not happen as one big pass or set of contiguous passes.
Rather, they are spread out throughout various parts of the
compilation process and use different intermediate representations.
For example,
type checking happens on the HIR, while borrow checking happens on the MIR.
Nonetheless, for the sake of presentation, we will discuss all of these
analyses in this part of the guide.

Src Doc Rustc Dev Guide Src Part 5 Intro (`src/doc/rustc-dev-guide/src/part-5-intro.md`) Copy Section

From MIR to binaries

All of the preceding chapters of this guide have one thing in common:
we never generated any executable machine code at all!
With this chapter, all of that changes.

So far,
we've shown how the compiler can take raw source code in text format
and transform it into MIR.
We have also shown how the compiler does various
analyses on the code to detect things like type or lifetime errors.
Now, we will finally take the MIR and produce some executable machine code.

NOTE: This part of a compiler is often called the backend.
The term is a bit overloaded because in the compiler source,
it usually refers to the "codegen backend" (i.e. LLVM, Cranelift, or GCC).
Usually, when you see the word "backend" in this part,
we are referring to the "codegen backend".

So what do we need to do?

1. First, we need to collect the set of things to generate code for.
   In particular,
   we need to find out which concrete types to substitute for generic ones,
   since we need to generate code for the concrete types.
   Generating code for the concrete types
   (i.e. emitting a copy of the code for each concrete type) is called monomorphization,
   so the process of collecting all the concrete types is called monomorphization collection.
2. Next, we need to actually lower the MIR to a codegen IR
   (usually LLVM IR) for each concrete type we collected.
3. Finally, we need to invoke the codegen backend,
   which runs a bunch of optimization passes,
   generates executable code,
   and links together an executable binary.

The code for codegen is actually a bit complex due to a few factors:

• Support for multiple codegen backends (LLVM, Cranelift, and GCC).
  We try to share as much backend code between them as possible,
  so a lot of it is generic over the codegen implementation.
  This means that there are often a lot of layers of abstraction.
• Codegen happens asynchronously in another thread for performance.
• The actual codegen is done by a third-party library (either of the 3 backends).

Generally, the rustc_codegen_ssa crate contains backend-agnostic code,
while the rustc_codegen_llvm crate contains code specific to LLVM codegen.

At a very high level, the entry point is
rustc_codegen_ssa::base::codegen_crate.
This function starts the process discussed in the rest of this chapter.

Src Doc Rustc Dev Guide Src Syntax Intro (`src/doc/rustc-dev-guide/src/syntax-intro.md`) Copy Section

Syntax and the AST

Working directly with source code is very inconvenient and error-prone.
Thus, before we do anything else, we convert raw source code into an
Abstract Syntax Tree (AST).
It turns out that doing this involves a lot of work,
including lexing, parsing, macro expansion, name resolution, conditional
compilation, feature-gate checking, and validation of the AST.
In this chapter, we take a look at all of these steps.

Notably, there isn't always a clean ordering between these tasks.
For example, macro expansion relies on name resolution to resolve the names of macros and imports.
And parsing requires macro expansion, which in turn may require parsing the output of the macro.

Src Doc Style Guide Src README (`src/doc/style-guide/src/README.md`) Copy Section

Rust Style Guide

Motivation - why use a formatting tool? Copy Chapter

Formatting code is a mostly mechanical task which takes both time and mental
effort. By using an automatic formatting tool, a programmer is relieved of
this task and can concentrate on more important things.

Furthermore, by sticking to an established style guide (such as this one),
programmers don't need to formulate ad hoc style rules, nor do they need to
debate with other programmers what style rules should be used, saving time,
communication overhead, and mental energy.

Humans comprehend information through pattern matching. By ensuring that all
Rust code has similar formatting, less mental effort is required to comprehend a
new project, lowering the barrier to entry for new developers.

Thus, there are productivity benefits to using a formatting tool (such as
rustfmt), and even larger benefits by using a community-consistent
formatting, typically by using a formatting tool's default settings.

The default Rust style Copy Chapter

The Rust Style Guide defines the default Rust style, and recommends that
developers and tools follow the default Rust style. Tools such as rustfmt use
the style guide as a reference for the default style. Everything in this style
guide, whether or not it uses language such as "must" or the imperative mood
such as "insert a space ..." or "break the line after ...", refers to the
default style.

This should not be interpreted as forbidding developers from following a
non-default style, or forbidding tools from adding any particular configuration
options.

Bugs Copy Chapter

If the style guide differs from rustfmt, that may represent a bug in rustfmt,
or a bug in the style guide; either way, please report it to the style team or
the rustfmt team or both, for investigation and fix.

If implementing a new formatting tool based on the style guide and default Rust
style, please test it on the corpus of existing Rust code, and avoid causing
widespread breakage. The implementation and testing of such a tool may surface
bugs in either the style guide or rustfmt, as well as bugs in the tool itself.

We typically resolve bugs in a fashion that avoids widespread breakage.

Formatting conventions Copy Chapter

Indentation and line width Copy Section

• Use spaces, not tabs.
• Each level of indentation must be 4 spaces (that is, all indentation
  outside of string literals and comments must be a multiple of 4).
• The maximum width for a line is 100 characters.

Block indent

Prefer block indent over visual indent:

// Block indent
a_function_call(
    foo,
    bar,
);

// Visual indent
a_function_call(foo,
                bar);

This makes for smaller diffs (e.g., if a_function_call is renamed in the above
example) and less rightward drift.

Trailing commas Copy Section

In comma-separated lists of any kind, use a trailing comma when followed by a
newline:

function_call(
    argument,
    another_argument,
);

let array = [
    element,
    another_element,
    yet_another_element,
];

This makes moving code (e.g., by copy and paste) easier, and makes diffs
smaller, as appending or removing items does not require modifying another line
to add or remove a comma.

Blank lines Copy Section

Separate items and statements by either zero or one blank lines (i.e., one or
two newlines). E.g,

fn foo() {
    let x = ...;

    let y = ...;
    let z = ...;
}

fn bar() {}
fn baz() {}

Trailing whitespace Copy Section

Do not include trailing whitespace on the end of any line. This includes blank
lines, comment lines, code lines, and string literals.

Note that avoiding trailing whitespace in string literals requires care to
preserve the value of the literal.

Sorting Copy Section

In various cases, the default Rust style specifies to sort things. If not
otherwise specified, such sorting should be "version sorting", which ensures
that (for instance) x8 comes before x16 even though the character 1 comes
before the character 8.

For the purposes of the Rust style, to compare two strings for version-sorting:

• Process both strings from beginning to end as two sequences of maximal-length
  chunks, where each chunk consists either of a sequence of characters other
  than ASCII digits, or a sequence of ASCII digits (a numeric chunk), and
  compare corresponding chunks from the strings.
• To compare two numeric chunks, compare them by numeric value, ignoring
  leading zeroes. If the two chunks have equal numeric value, but different
  numbers of leading digits, and this is the first time this has happened for
  these strings, treat the chunks as equal (moving on to the next chunk) but
  remember which string had more leading zeroes.
• To compare two chunks if both are not numeric, compare them by Unicode
  character lexicographically, with two exceptions:
  • _ (underscore) sorts immediately after (space) but before any other
    character. (This treats underscore as a word separator, as commonly used in
    identifiers.)
  • Unless otherwise specified, version-sorting should sort non-lowercase
    characters (characters that can start an UpperCamelCase identifier)
    before lowercase characters.
• If the comparison reaches the end of the string and considers each pair of
  chunks equal:
  • If one of the numeric comparisons noted the earliest point at which one
    string had more leading zeroes than the other, sort the string with more
    leading zeroes first.
  • Otherwise, the strings are equal.

Note that there exist various algorithms called "version sorting", which
generally try to solve the same problem, but which differ in various ways (such
as in their handling of numbers with leading zeroes). This algorithm
does not purport to precisely match the behavior of any particular other
algorithm, only to produce a simple and satisfying result for Rust formatting.
In particular, this algorithm aims to produce a satisfying result for a set of
symbols that have the same number of leading zeroes, and an acceptable and
easily understandable result for a set of symbols that has varying numbers of
leading zeroes.

As an example, version-sorting will sort the following strings in the order
given:

• _ZYXW
• _abcd
• A2
• ABCD
• Z_YXW
• ZY_XW
• ZY_XW
• ZYXW
• ZYXW_
• a1
• abcd
• u_zzz
• u8
• u16
• u32
• u64
• u128
• u256
• ua
• usize
• uz
• v000
• v00
• v0
• v0s
• v00t
• v0u
• v001
• v01
• v1
• v009
• v09
• v9
• v010
• v10
• w005s09t
• w5s009t
• x64
• x86
• x86_32
• x86_64
• x86_128
• x87
• zyxw

[Module-level items](items.md) Copy Section

[Statements](statements.md) Copy Section

[Expressions](expressions.md) Copy Section

[Types](types.md) Copy Section

Comments Copy Section

The following guidelines for comments are recommendations only, a mechanical
formatter might skip formatting of comments.

Prefer line comments (//) to block comments (/* ... */).

When using line comments, put a single space after the opening sigil.

When using single-line block comments, put a single space after the opening
sigil and before the closing sigil. For multi-line block comments, put a
newline after the opening sigil, and a newline before the closing sigil.

Prefer to put a comment on its own line. Where a comment follows code, put a
single space before it. Where a block comment appears inline, use surrounding
whitespace as if it were an identifier or keyword.

Examples:

// A comment on an item.
struct Foo { ... }

fn foo() {} // A comment after an item.

pub fn foo(/* a comment before an argument */ x: T) {...}

Comments should usually be complete sentences. Start with a capital letter, end
with a period (.). An inline block comment may be treated as a note without
punctuation.

Source lines which are entirely a comment should be limited to 80 characters
in length (including comment sigils, but excluding indentation) or the maximum
width of the line (including comment sigils and indentation), whichever is
smaller:

// This comment goes up to the ................................. 80 char margin.

{
    // This comment is .............................................. 80 chars wide.
}

{
    {
        {
            {
                {
                    {
                        // This comment is limited by the ......................... 100 char margin.
                    }
                }
            }
        }
    }
}

Doc comments

Prefer line comments (///) to block comments (/** ... */).

Prefer outer doc comments (/// or /** ... */), only use inner doc comments
(//! and /*! ... */) to write module-level or crate-level documentation.

Put doc comments before attributes.

Attributes Copy Section

Put each attribute on its own line, indented to the level of the item.
In the case of inner attributes (#!), indent it to the level of the inside of
the item. Prefer outer attributes, where possible.

For attributes with argument lists, format like functions.

#[repr(C)]
#[foo(foo, bar)]
#[long_multi_line_attribute(
    split,
    across,
    lines,
)]
struct CRepr {
    #![repr(C)]
    x: f32,
    y: f32,
}

For attributes with an equal sign, put a single space before and after the =,
e.g., #[foo = 42].

There must only be a single derive attribute. Note for tool authors: if
combining multiple derive attributes into a single attribute, the ordering of
the derived names must generally be preserved for correctness:
#[derive(Foo)] #[derive(Bar)] struct Baz; must be formatted to
#[derive(Foo, Bar)] struct Baz;.

*small* items Copy Section

In many places in this guide we specify formatting that depends on a code
construct being small. For example, single-line vs multi-line struct
literals:

// Normal formatting
Foo {
    f1: an_expression,
    f2: another_expression(),
}

// "small" formatting
Foo { f1, f2 }

We leave it to individual tools to decide on exactly what small means. In
particular, tools are free to use different definitions in different
circumstances.

Some suitable heuristics are the size of the item (in characters) or the
complexity of an item (for example, that all components must be simple names,
not more complex sub-expressions). For more discussion on suitable heuristics,
see this issue.

[Non-formatting conventions](advice.md) Copy Chapter

[Cargo.toml conventions](cargo.md) Copy Chapter

[Principles used for deciding these guidelines](principles.md) Copy Chapter

Src Doc Rustc Dev Guide Src Appendix Code Index (`src/doc/rustc-dev-guide/src/appendix/code-index.md`) Copy Section

Code Index

rustc has a lot of important data structures.
This is an attempt to give some guidance on where to learn more
about some of the key data structures of the compiler.

Src Doc Rustc Dev Guide Src Building Quickstart (`src/doc/rustc-dev-guide/src/building/quickstart.md`) Copy Section

Quickstart

This is a quickstart guide about getting the compiler running.
For more information on the individual steps, see the other pages in this chapter.

First, clone the repository:

git clone https://github.com/rust-lang/rust.git
cd rust

When building the compiler, we don't use cargo directly;
instead we use a wrapper called "x", which is invoked with ./x.

We need to create a configuration for the build.
Use ./x setup to create a good default.

./x setup

Then, we can build the compiler.
Use ./x build to build the compiler, standard library, and a few tools.
You can also ./x check to just check it.
All these commands can take specific components/paths as arguments, for example ./x check compiler to just check the compiler.

./x build

When doing a change to the compiler that does not affect the way it compiles
the standard library (so for example, a change to an error message), use
--keep-stage-std 1 to avoid recompiling it.

After building the compiler and standard library, you now have a working compiler toolchain.
You can use it with rustup by linking it.

rustup toolchain link stage1 build/host/stage1

NOTE: If you use ./x setup tools, the default stage will be set to 2 instead of 1.
Adjust your command accordingly:

rustup toolchain link stage2 build/host/stage2

Now you have a toolchain called stage1 linked to your build.
You can use it to test the compiler.

rustc +stage1 testfile.rs

After doing a change, you can run the compiler test suite with ./x test.

./x test runs the full test suite, which is slow and rarely what you want.
Usually, ./x test tests/ui is what you want after a compiler change, testing
all UI tests that invoke the compiler on a specific test file
and check the output.

./x test tests/ui

Use --bless if you've made a change and want to update the .stderr files with the new output.

Congrats, you are now ready to make a change to the compiler!
If you have more questions, the full chapter might contain the
answers, and if it doesn't, feel free to ask for help on
Zulip.

If you use VSCode, Vim, Emacs, Helix or Zed, ./x setup will ask you if you want to
set up the editor config.
For more information, check out suggested workflows.

Src Doc Rustc Dev Guide Src Debuginfo Intro (`src/doc/rustc-dev-guide/src/debuginfo/intro.md`) Copy Section

Debug info

Debug info is a collection of information generated by the compiler that allows debuggers to
correctly interpret the state of a program while it is running.
That includes things like mapping instruction addresses to lines of code in the source file,
and type layout information so that bytes in memory can be read and displayed in a meaningful way.

Debug info can be a slightly overloaded term, covering all the layers between Rust MIR, and the
end-user seeing the output of their debugger onscreen.
In brief, the stack from beginning to end is as follows:

1. Rustc inspects the MIR and communicates the relevant source, symbol, and type information to LLVM
2. LLVM translates this information into a target-specific debug info format during compilation
3. A debugger reads and interprets the debug info, mapping source-lines and allowing the debugee's
   variables in memory to be located and read with the correct layout
4. Built-in debugger formatting and styling is applied to variables
5. User-defined scripts are run, formatting and styling the variables further
6. The debugger frontend displays the variable to the user, possibly through the means of additional
   API layers (e.g. VSCode extension by way of the
   Debug Adapter Protocol)

NOTE: This subsection of the dev guide is perhaps more detailed than necessary. It aims to collect
a large amount of scattered information into one place and equip the reader with as firm a grasp of
the entire debug stack as possible.

If you are only interested in working on the visualizer
scripts, the information in the debugger-visualizers and
testing will suffice. If you need to make changes to Rust's debug node generation,
please see rust-codegen. All other sections are supplementary, but can be
vital to understanding some of the compromises the visualizers or codegen need to make. It can
also be valuable to know when a problem might be better solved in LLVM or the debugger itself.

DWARF

The is the primary debug info format for *-gnu targets.
It is typically bundled in with the
binary, but it can be generated as a separate file.
The DWARF standard is available here.

NOTE: To inspect DWARF debug info, gimli can be used
programatically. If you prefer a GUI, the author recommends DWEX

PDB/CodeView

The primary debug info format for *-msvc targets.
PDB is a proprietary container format created by Microsoft that, unfortunately,
has multiple meanings.
We are concerned with ordinary PDB files, as Portable PDB is used mainly for .Net applications.
PDB files are separate from the compiled binary and use the .pdb extension.

PDB files contain CodeView objects, equivalent to DWARF's tags.
CodeView, the debugger that consumed CodeView objects, was originally released in 1985.
Its original intent was for C debugging,
and was later extended to support Visual C++.
There are still minor alterations to the format to support modern architectures and languages,
but many of these changes are undocumented and/or sparsely used.

It is important to keep this context in mind when working with CodeView objects.
Due to its origins,
the "feature-set" of these objects is very limited, and focused around the core features of C.
It does not have many of the convenience or features of modern DWARF standards.
A fair number of workarounds exist within the debug info stack
to compensate for CodeView's shortcomings.

Due to its proprietary nature, it is very difficult to find information about PDB and CodeView.
Many of the sources were made at vastly different times
and contain incomplete or somewhat contradictory information.
As such, this page will aim to collect as many sources as possible.

• TIS PE specification
  which includes a lengthy section titled "Microsoft Symbol and Type Information", detailing much of
  the CodeView format.
  The document was created in 1993, but the information is still detailed,
  accurate, and has useful diagrams.
• LLVM
  • CodeView Overview
  • PDB Overview and technical details
• Microsoft
  • microsoft-pdb - A C/C++ implementation of a PDB
    reader.
    The implementation does not contain the full PDB or CodeView specification, but does
    contain enough information for other PDB consumers to be written.
    At time of writing (Nov 2025),
    this repo has been archived for several years.
  • pdb-rs - A Rust-based PDB reader and writer based on
    other publicly-available information.
    Does not guarantee stability or spec compliance.
    Also contains pdbtool, which can dump PDB files (cargo install --locked pdbtool)
  • Debug Interface Access SDK.
    While it does not document the PDB format directly, details can be gleaned from the interface
    itself.
  • PDB-Documentation - a resource compiling
    much of the publicly available information about PDB and CodeView.

Debuggers

Rust supports 3 major debuggers: GDB, LLDB, and CDB.
Each has its own set of requirements,
limitations, and quirks.
This unfortunately creates a large surface area to account for.

NOTE: CDB is a proprietary debugger created by Microsoft.
The underlying engine also powers WinDbg, KD, the Microsoft C/C++ extension for VSCode,
and part of the Visual Studio Debugger.
In these docs, it will be referred to as CDB for consistency

While GDB and LLDB do offer facilities to natively support Rust's value layout, this isn't
completely necessary.
Rust currently outputs debug info very similar to that of C++, allowing
debuggers without Rust support to work with a slightly degraded experience.
More detail will be included in later sections,
but here is a quick reference for the capabilities of each debugger:

IMPORTANT: CDB can be assumed to run only on Windows. No assumptions can be made about the OS
running GDB or LLDB.

Unsupported Copy Chapter

Below, are several unsupported debuggers that are of particular note due to their potential impact
in the future.

• Bugstalker is an x86-64 Linux debugger written in Rust,
  specifically to debug Rust programs.
  While promising, it is still in early development.
• RAD Debugger is a Windows-only GUI debugger.
  It has a custom debug info format that PDB is translated into.
  The project also includes a linker that can generate their new debug info format
  during the linking phase.

Src Doc Rustc Dev Guide Src Mir Index (`src/doc/rustc-dev-guide/src/mir/index.md`) Copy Section

The MIR (Mid-level IR)

MIR is Rust's Mid-level Intermediate Representation.
It is constructed from HIR.
MIR was introduced in RFC 1211.
It is a radically simplified form of Rust that is used for
certain flow-sensitive safety checks – notably the borrow checker!
– and also for optimization and code generation.

If you'd like a very high-level introduction to MIR,
as well as some of the compiler concepts that it relies on (such as control-flow
graphs and desugaring), you may enjoy the rust-lang blog post that introduced MIR.

Introduction to MIR Copy Chapter

MIR is defined in the compiler/rustc_middle/src/mir/ module,
but much of the code that manipulates it is found in compiler/rustc_mir_build,
compiler/rustc_mir_transform,
and compiler/rustc_mir_dataflow.

Some of the key characteristics of MIR are:

• It is based on a control-flow graph.
• It does not have nested expressions.
• All types in MIR are fully explicit.

Key MIR vocabulary Copy Chapter

This section introduces the key concepts of MIR, summarized here:

• Basic blocks: units of the control-flow graph, consisting of:
  • statements: actions with one successor
  • terminators: actions with potentially multiple successors; always at the end of a block
  • (if you're not familiar with the term basic block, see the background chapter)
• Locals: Memory locations allocated on the stack (conceptually, at least),
  such as function arguments, local variables, and temporaries.
  These are identified by an index, written with a leading underscore, like _1.
  There is also a special "local" (_0) allocated to store the return value.
• Places: expressions that identify a location in memory, like _1 or _1.f.
• Rvalues: expressions that produce a value.
  The "R" stands for the fact that these are the "right-hand side" of an assignment.
  • Operands: the arguments to an rvalue,
    which can either be a constant (like 22) or a place (like _1).

You can get a feeling for how MIR is constructed by translating simple
programs into MIR and reading the pretty printed output.
In fact, the playground makes this easy,
since it supplies a MIR button that will show you the MIR for your program.
Try putting this program into play (or clicking on this link),
and then clicking the "MIR" button on the top:

fn main() {
    let mut vec = Vec::new();
    vec.push(1);
    vec.push(2);
}

You should see something like:

// WARNING: This output format is intended for human consumers only
// and is subject to change without notice. Knock yourself out.
fn main() -> () {
    ...
}

This is the MIR format for the main function.
MIR shown by above link is optimized.
Some statements like StorageLive are removed in optimization.
This happens because the compiler notices the value is never accessed in the code.
We can use rustc [filename].rs -Z mir-opt-level=0 --emit mir to view unoptimized MIR.
This requires the nightly toolchain.

Variable declarations. If we drill in a bit,
we'll see it begins with a bunch of variable declarations.
They look like this:

let mut _0: ();                      // return place
let mut _1: std::vec::Vec<i32>;      // in scope 0 at src/main.rs:2:9: 2:16
let mut _2: ();
let mut _3: &mut std::vec::Vec<i32>;
let mut _4: ();
let mut _5: &mut std::vec::Vec<i32>;

You can see that variables in MIR don't have names, they have indices,
like _0 or _1. We also intermingle the user's variables (e.g.,
_1) with temporary values (e.g., _2 or _3). You can tell apart
user-defined variables because they have debuginfo associated to them (see below).

User variable debuginfo. Below the variable declarations,
we find the only hint that _1 represents a user variable:

scope 1 {
    debug vec => _1;                 // in scope 1 at src/main.rs:2:9: 2:16
}

Each debug <Name> => ; annotation describes a named user variable,
and where (i.e. the place) a debugger can find the data of that variable.
Here the mapping is trivial, but optimizations may complicate the place,
or lead to multiple user variables sharing the same place.
Additionally, closure captures are described using the same system, and so
they're complicated even without optimizations, e.g.: debug x => (*((*_1).0: &T));.

The "scope" blocks (e.g., scope 1 { .. }) describe the lexical structure of
the source program (which names were in scope when), so any part of the program
annotated with // in scope 0 would be missing vec, if you were stepping
through the code in a debugger, for example.

Basic blocks. Reading further, we see our first basic block (naturally
it may look slightly different when you view it, and I am ignoring some of the comments):

bb0: {
    StorageLive(_1);
    _1 = const <std::vec::Vec<T>>::new() -> bb2;
}

A basic block is defined by a series of statements and a final terminator.
In this case, there is one statement:

StorageLive(_1);

This statement indicates that the variable _1 is "live",
meaning that it may be used later – this will persist until we encounter a
StorageDead(_1) statement, which indicates that the variable _1 is done being used.
These "storage statements" are used by LLVM to allocate stack space.

The terminator of the block bb0 is the call to Vec::new:

_1 = const <std::vec::Vec<T>>::new() -> bb2;

Terminators are different from statements because they can have more
than one successor – that is, control may flow to different places.
Function calls like the call to Vec::new are always
terminators because of the possibility of unwinding,
although in the case of Vec::new we are able to see that indeed unwinding is not possible,
and hence we list only one successor block, bb2.

If we look ahead to bb2, we will see it looks like this:

bb2: {
    StorageLive(_3);
    _3 = &mut _1;
    _2 = const <std::vec::Vec<T>>::push(move _3, const 1i32) -> [return: bb3, unwind: bb4];
}

Here there are two statements: another StorageLive, introducing the _3 temporary,
and then an assignment:

_3 = &mut _1;

Assignments in general have the form:

<Place> = <Rvalue>

A place is an expression like _3, _3.f or *_3 – it denotes a location in memory.
An Rvalue is an expression that creates a value: in this case,
the rvalue is a mutable borrow expression, which looks like &mut .
So we can kind of define a grammar for rvalues like so:

<Rvalue>  = & (mut)? <Place>
          | <Operand> + <Operand>
          | <Operand> - <Operand>
          | ...

<Operand> = Constant
          | copy Place
          | move Place

As you can see from this grammar,
rvalues cannot be nested – they can only reference places and constants.
Moreover, when you use a place,
we indicate whether we are copying it (which requires that the
place have a type T where T: Copy) or moving it (which works for a place of any type).
So, for example, if we had the expression x = a + b + c in Rust,
that would get compiled to two statements and a temporary:

TMP1 = a + b
x = TMP1 + c

(Try it and see,
though you may want to do release mode to skip over the overflow checks.)

MIR data types Copy Chapter

The MIR data types are defined in the compiler/rustc_middle/src/mir/ module.
Each of the key concepts mentioned in the previous section
maps in a fairly straightforward way to a Rust type.

The main MIR data type is Body.
It contains the data for a single
function (along with sub-instances of Mir for "promoted constants",
but you can read about those below).

• Basic blocks: The basic blocks are stored in the field
  Body::basic_blocks; this is a vector of BasicBlockData structures.
  Nobody ever references a basic block directly: instead, we pass around BasicBlock values,
  which are newtype'd indices into this vector.
• Statements are represented by the type Statement.
• Terminators are represented by the Terminator.
• Locals are represented by a newtype'd index type Local.
  The data for a local variable is found in the Body::local_decls vector.
  There is also a special constant
  RETURN_PLACE identifying the special "local" representing the return value.
• Places are identified by the struct Place.
  There are a few fields:
  • Local variables like _1
  • Projections, which are fields or other things that "project out" from a base place.
    These are represented by the newtype'd type
    ProjectionElem. So e.g. the place _1.f is a projection,
    with f being the "projection element" and _1 being the base path.
    *_1 is also a projection,
    with the * being represented by the ProjectionElem::Deref element.
• Rvalues are represented by the enum Rvalue.
• Operands are represented by the enum Operand.

Representing constants Copy Chapter

When code has reached the MIR stage, constants can generally come in two forms:
MIR constants (mir::Constant) and type system constants (ty::Const).
MIR constants are used as operands: in x + CONST, CONST is a MIR constant;
similarly, in x + 2, 2 is a MIR constant.
Type system constants are used in the type system,
in particular for array lengths, but also for const generics.

Generally, both kinds of constants can be "unevaluated" or "already evaluated".
An unevaluated constant simply stores the DefId of what needs to be evaluated
to compute this result.
An evaluated constant (a "value") has already been
computed; their representation differs between type system constants and MIR
constants: MIR constants evaluate to a mir::ConstValue; type system constants
evaluate to a ty::ValTree.

Type system constants have some more variants to support const generics: they
can refer to local const generic parameters, and they are subject to inference.
Furthermore, the mir::Constant::Ty variant lets us use an arbitrary type
system constant as a MIR constant; this happens whenever a const generic
parameter is used as an operand.

MIR constant values Copy Section

In general,
a MIR constant value (mir::ConstValue) was computed by evaluating some constant the user wrote.
This const evaluation produces
a very low-level representation of the result in terms of individual bytes.
We call this an "indirect" constant (mir::ConstValue::Indirect) since the value
is stored in-memory.

However, storing everything in-memory would be awfully inefficient.
Hence there are some other variants in mir::ConstValue that can represent certain simple
and common values more efficiently.
In particular, everything that can be directly written as a literal in Rust (integers,
floats, chars, bools,
but also "string literals" and b"byte string literals") has an optimized variant that
avoids the full overhead of the in-memory representation.

ValTrees Copy Section

An evaluated type system constant is a "valtree".
The ty::ValTree datastructure allows us to represent

• arrays,
• many structs,
• tuples,
• enums and,
• most primitives.

The most important rule for this representation is that every value must be uniquely represented.
In other words, a specific value must only be representable in one specific way.
For example, there is only one way to represent an array of two integers as a ValTree:
Branch([Leaf(first_int), Leaf(second_int)]).
Even though theoretically a [u32; 2] could be encoded in a u64 and thus just be a
Leaf(bits_of_two_u32), that is not a legal construction of ValTree (and is very complex to do,
so it is unlikely anyone is tempted to do so).

These rules also mean that some values are not representable.
There can be no unions in type level constants,
as it is not clear how they should be represented,
because their active variant is unknown.
Similarly, there is no way to represent raw pointers as addresses are unknown at compile-time,
and thus we cannot make any assumptions about them.
References on the other hand can be represented,
as equality for references is defined as equality on their value,
so we ignore their address and just look at the backing value.
We must make sure that the pointer values of the references are not observable at compile time.
We thus encode &42 exactly like 42.
Any conversion from valtree back to a MIR constant value must reintroduce an actual indirection.
At codegen time,
the addresses may be deduplicated between multiple uses or not,
entirely depending on arbitrary optimization choices.

As a consequence, all decoding of ValTree must happen by matching on the type first and making
decisions depending on that.
The value itself gives no useful information without the type that belongs to it.

Promoted constants Copy Section

See the const-eval WG's docs on promotion.

Src Doc Rustc Dev Guide Src Rustc Driver Intro (`src/doc/rustc-dev-guide/src/rustc-driver/intro.md`) Copy Section

`rustc_driver` and `rustc_interface`

`rustc_driver` Copy Chapter

The rustc_driver is essentially rustc's main function.
It acts as the glue for running the various phases of the compiler in the correct order,
using the interface defined in the rustc_interface crate.
Where possible, using rustc_driver rather than rustc_interface is recommended.

The main entry point of rustc_driver is rustc_driver::compiler_entrypoint.
This builder accepts the same command-line args as rustc as well as an implementation of Callbacks and a couple of other optional options.
Callbacks is a trait that allows for custom compiler configuration,
as well as allowing custom code to run after different phases of the compilation.

`rustc_interface` Copy Chapter

The rustc_interface crate provides a low level API to external users for manually driving the compilation process,
allowing third parties to effectively use rustc's internals as a library for analyzing a crate or for ad hoc emulating of the compiler for cases where rustc_driver is not flexible enough (i.e. rustdoc compiling code and serving output).

The main entry point of rustc_interface (rustc_interface::run_compiler) takes a configuration variable for the compiler
and a closure taking a yet unresolved Compiler.
run_compiler creates a Compiler from the configuration and passes it to the closure.
Inside the closure you can use the Compiler to call various functions to compile a crate and get the results.
You can see a minimal example of how to use rustc_interface here.

You can see an example of how to use the various functions using rustc_interface needs by looking at the rustc_driver implementation,
specifically rustc_driver_impl::compiler_entrypoint
(not to be confused with rustc_interface::run_compiler).

Warning: By its very nature, the internal compiler APIs are always going
to be unstable. That said, we do try not to break things unnecessarily.

Src Doc Rustc Dev Guide Src Tests Intro (`src/doc/rustc-dev-guide/src/tests/intro.md`) Copy Section

Testing the compiler

The Rust project runs a wide variety of different tests,
orchestrated by the build system (./x test).
This section gives a brief overview of the different testing tools.
Subsequent chapters dive into running tests and adding new tests.

Kinds of tests Copy Chapter

There are several kinds of tests to exercise things in the Rust distribution.
Almost all of them are driven by ./x test, with some exceptions noted below.

Compiletest Copy Section

The main test harness for testing the compiler itself is a tool called compiletest.

compiletest supports running different styles of tests,
organized into test suites.
A test mode may provide common presets/behavior for a set of test suites.
compiletest-supported tests are located in the tests directory.

The Compiletest chapter goes into detail on how to use this tool.

Example: ./x test tests/ui

Package tests Copy Section

The standard library and many of the compiler packages include typical Rust #[test] unit tests,
integration tests, and documentation tests.
You can pass a path to ./x test for almost any package in the library/ or compiler/
directory, and x will essentially run cargo test on that package.

Examples:

The standard library relies very heavily on documentation tests to cover its functionality.
However, unit tests and integration tests can also be used as needed.
Almost all of the compiler packages have doctests disabled.

All standard library and compiler unit tests are placed in separate tests file
(which is enforced in tidy).
This ensures that when the test file is changed, the crate does not need to be recompiled.
For example:

#[cfg(test)]
mod tests;

If it wasn't done this way, and you were working on something like core, that
would require recompiling the entire standard library, and the entirety of rustc.

./x test includes some CLI options for controlling the behavior with these package tests:

• --doc — Only runs documentation tests in the package.
• --all-targets — Run all tests except documentation tests.
• --tests — Only runs unit and integration tests

Tidy Copy Section

Tidy is a custom tool used for validating source code style and formatting conventions,
such as rejecting long lines.
There is more information in the
section on coding conventions or the Tidy Readme.

Examples: ./x test tidy

Formatting Copy Section

Rustfmt is integrated with the build system to enforce uniform style across the compiler.
The formatting check is automatically run by the Tidy tool mentioned above.

Examples:

Book documentation tests Copy Section

All of the books that are published have their own tests,
primarily for validating that the Rust code examples pass.
Under the hood, these are essentially using rustdoc --test on the markdown files.
The tests can be run by passing a path to a book to ./x test.

Example: ./x test src/doc/book

Documentation link checker Copy Section

Links across all documentation is validated with a link checker tool,
and it can be invoked so:

./x test linkchecker

This requires building all of the documentation, which might take a while.

`distcheck` Copy Section

distcheck verifies that the source distribution tarball created by the build system will unpack,
build, and run all tests.

./x test distcheck

Tool tests Copy Section

Packages that are included with Rust have all of their tests run as well.
This includes things such as cargo, clippy, rustfmt, miri, bootstrap (testing the
Rust build system itself), etc.

Most of the tools are located in the src/tools directory.
To run the tool's tests, just pass its path to ./x test.

Example: ./x test src/tools/cargo

Usually these tools involve running cargo test within the tool's directory.

If you want to run only a specified set of tests, append --test-args FILTER_NAME to the command.

Example: ./x test src/tools/miri --test-args padding

In CI, some tools are allowed to fail.
Failures send notifications to the corresponding teams, and are tracked on the toolstate website.
More information can be found in the toolstate documentation.

Ecosystem testing Copy Section

Rust tests integration with real-world code to catch regressions and make
informed decisions about the evolution of the language.
There are several kinds of ecosystem tests, including Crater.
See the Ecosystem testing chapter for more details.

Performance testing Copy Section

A separate infrastructure is used for testing and tracking performance of the compiler.
See the Performance testing chapter for more details.

Codegen backend testing Copy Section

See Codegen backend testing.

Miscellaneous information Copy Chapter

There are some other useful testing-related info at Misc info.

Further reading Copy Chapter

The following blog posts may also be of interest:

• brson's classic "How Rust is tested"

Src Doc Rustc Src Codegen Options Index (`src/doc/rustc/src/codegen-options/index.md`) Copy Section

Codegen Options

All of these options are passed to rustc via the -C flag, short for "codegen." You can see
a version of this list for your exact compiler by running rustc -C help.

code-model Copy Chapter

This option lets you choose which code model to use.
Code models put constraints on address ranges that the program and its symbols may use.
With smaller address ranges machine instructions
may be able to use more compact addressing modes.

The specific ranges depend on target architectures and addressing modes available to them.
For x86 more detailed description of its code models can be found in
System V Application Binary Interface
specification.

Supported values for this option are:

• tiny - Tiny code model.
• small - Small code model. This is the default model for majority of supported targets.
• kernel - Kernel code model.
• medium - Medium code model.
• large - Large code model.

Supported values can also be discovered by running rustc --print code-models.

codegen-units Copy Chapter

This flag controls the maximum number of code generation units the crate is
split into. It takes an integer greater than 0.

When a crate is split into multiple codegen units, LLVM is able to process
them in parallel. Increasing parallelism may speed up compile times, but may
also produce slower code. Setting this to 1 may improve the performance of
generated code, but may be slower to compile.

The default value, if not specified, is 16 for non-incremental builds. For
incremental builds the default is 256 which allows caching to be more granular.

collapse-macro-debuginfo Copy Chapter

This flag controls whether code locations from a macro definition are collapsed into a single
location associated with that macro's call site, when generating debuginfo for this crate.

This option, if passed, overrides both default collapsing behavior and #[collapse_debuginfo]
attributes in code.

• y, yes, on, true: collapse code locations in debuginfo.
• n, no, off or false: do not collapse code locations in debuginfo.
• external: collapse code locations in debuginfo only if the macro comes from a different crate.

control-flow-guard Copy Chapter

This flag controls whether LLVM enables the Windows Control Flow
Guard
platform security feature. This flag is currently ignored for non-Windows targets.
It takes one of the following values:

• y, yes, on, true, checks, or no value: enable Control Flow Guard.
• nochecks: emit Control Flow Guard metadata without runtime enforcement checks (this
  should only be used for testing purposes as it does not provide security enforcement).
• n, no, off, false: do not enable Control Flow Guard (the default).

debug-assertions Copy Chapter

This flag lets you turn cfg(debug_assertions) conditional
compilation on
or off. It takes one of the following values:

• y, yes, on, true, or no value: enable debug-assertions.
• n, no, off or false: disable debug-assertions.

If not specified, debug assertions are automatically enabled only if the
opt-level is 0.

debuginfo Copy Chapter

This flag controls the generation of debug information. It takes one of the
following values:

• 0 or none: no debug info at all (the default).
• line-directives-only: line info directives only. For the nvptx* targets this enables profiling. For other use cases, line-tables-only is the better, more compatible choice.
• line-tables-only: line tables only. Generates the minimal amount of debug info for backtraces with filename/line number info, but not anything else, i.e. no variable or function parameter info.
• 1 or limited: debug info without type or variable-level information.
• 2 or full: full debug info.

Note: The -g flag is an alias for -C debuginfo=2.

default-linker-libraries Copy Chapter

This flag controls whether or not the linker includes its default libraries.
It takes one of the following values:

• y, yes, on, true: include default libraries.
• n, no, off or false or no value: exclude default libraries (the default).

For example, for gcc flavor linkers, this issues the -nodefaultlibs flag to
the linker.

dlltool Copy Chapter

On windows-gnu targets, this flag controls which dlltool rustc invokes to
generate import libraries when using the raw-dylib link kind.
It takes a path to the dlltool executable.
If this flag is not specified, a dlltool executable will be inferred based on
the host environment and target.

dwarf-version Copy Chapter

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 Copy Chapter

This flag controls whether or not the compiler embeds LLVM bitcode into object
files. It takes one of the following values:

• y, yes, on, true or no value: put bitcode in rlibs (the default).
• n, no, off or false: omit bitcode from rlibs.

LLVM bitcode is required when rustc is performing link-time optimization (LTO).
Embedded bitcode will appear in rustc-generated object files inside of a section
whose name is defined by the target platform. Most of the time this is .llvmbc.

The use of -C embed-bitcode=no can significantly improve compile times and
reduce generated file sizes if your compilation does not actually need bitcode
(e.g. if you're not performing LTO). For these reasons, Cargo uses -C embed-bitcode=no
whenever possible. Likewise, if you are building directly with rustc we recommend
using -C embed-bitcode=no whenever you are not using LTO.

If combined with -C lto, -C embed-bitcode=no will cause rustc to abort
at start-up, because the combination is invalid.

Note: if you're building Rust code with LTO then you probably don't even
need the embed-bitcode option turned on. You'll likely want to use
-Clinker-plugin-lto instead which skips generating object files entirely and
simply replaces object files with LLVM bitcode. The only purpose for
-Cembed-bitcode is when you're generating an rlib that is both being used
with and without LTO. For example Rust's standard library ships with embedded
bitcode since users link to it both with and without LTO.

This also may make you wonder why the default is yes for this option. The
reason for that is that it's how it was for rustc 1.44 and prior. In 1.45 this
option was added to turn off what had always been the default.

embed-metadata Copy Chapter

This option instructs rustc to include the full metadata in rlib and dylib
crate types. The default value is yes (enabled). If disabled (no), only stub
metadata will be stored in these files, to reduce their size on disk. When using
-Cembed-metadata=no, you will probably want to use --emit=metadata to produce
the full metadata into a separate .rmeta file.

extra-filename Copy Chapter

This option allows you to put extra data in each output filename. It takes a
string to add as a suffix to the filename. See the --emit
flag for more information.

force-frame-pointers Copy Chapter

This flag forces the use of frame pointers. It takes one of the following
values:

• y, yes, on, true or no value: force-enable frame pointers.
• n, no, off or false: do not force-enable frame pointers. This does
  not necessarily mean frame pointers will be removed.

The default behaviour, if frame pointers are not force-enabled, depends on the
target.

force-unwind-tables Copy Chapter

This flag forces the generation of unwind tables. It takes one of the following
values:

• y, yes, on, true or no value: Unwind tables are forced to be generated.
• n, no, off or false: Unwind tables are not forced to be generated. If unwind
  tables are required by the target an error will be emitted.

The default if not specified depends on the target.

incremental Copy Chapter

This flag allows you to enable incremental compilation, which allows rustc
to save information after compiling a crate to be reused when recompiling the
crate, improving re-compile times. This takes a path to a directory where
incremental files will be stored.

Using incremental compilation inhibits certain optimizations (for example by increasing the amount of codegen units) and is therefore not recommended for release builds.

instrument-coverage Copy Chapter

This option enables instrumentation-based code coverage support. See the
chapter on instrumentation-based code coverage for more information.

Note that while the -C instrument-coverage option is stable, the profile data
format produced by the resulting instrumentation may change, and may not work
with coverage tools other than those built and shipped with the compiler.

jump-tables Copy Chapter

This option is used to allow or prevent the LLVM codegen backend from creating
jump tables when lowering switches from Rust code.

• y, yes, on, true or no value: allow jump tables (the default).
• n, no, off or false: disable jump tables.

To prevent jump tables being created from Rust code, a target must ensure
all crates are compiled with jump tables disabled.

Note, in many cases the Rust toolchain is distributed with precompiled
crates, such as the core and std crates, which could possibly include
jump tables. Furthermore, this option does not guarantee a target will
be free of jump tables. They could arise from external dependencies,
inline asm, or other complicated interactions when using crates which
are compiled with jump table support.

Disabling jump tables can be used to help provide protection against
jump-oriented-programming (JOP) attacks.

link-arg Copy Chapter

This flag lets you append a single extra argument to the linker invocation.

"Append" is significant; you can pass this flag multiple times to add multiple arguments.

On Unix-like targets that use cc as the linker driver, use -Clink-arg=-Wl,$ARG to pass an argument to the actual linker.

link-args Copy Chapter

This flag lets you append multiple extra arguments to the linker invocation. The
options should be separated by spaces.

link-dead-code Copy Chapter

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: try to keep dead code.
• n, no, off or false: remove dead code (the default).

This flag was historically used to help improve some older forms of code
coverage measurement. Its use is not recommended.

link-self-contained Copy Chapter

This flag controls whether the linker will use libraries and objects shipped with Rust instead of
those in the system. It also controls which binary is used for the linker itself. This allows
overriding cases when detection fails or the user wants to use shipped libraries.

You can enable or disable the usage of any self-contained components using one of the following values:

• no value: rustc will use heuristic to disable self-contained mode if system has necessary tools.
• y, yes, on, true: use only libraries/objects shipped with Rust.
• n, no, off or false: rely on the user or the linker to provide non-Rust libraries/objects.

It is also possible to enable or disable specific self-contained components in a more granular way.
You can pass a comma-separated list of self-contained components, individually enabled
(+component) or disabled (-component).

Currently, only the linker granular option is stabilized, and only on the x86_64-unknown-linux-gnu target:

• linker: toggle the usage of self-contained linker binaries (linker, dlltool, and their necessary libraries)

Note that only the -linker opt-out is stable on the x86_64-unknown-linux-gnu target: +linker is
already the default on this target.

Implementation notes

On the x86_64-unknown-linux-gnu target, when using the default linker flavor (using cc as the
linker driver) and linker features (to try using lld), rustc will try to use the self-contained
linker by passing a -B /path/to/sysroot/ link argument to the driver to find rust-lld in the
sysroot. For backwards-compatibility, and to limit name and PATH collisions, this is done using a
shim executable (the lld-wrapper tool) that forwards execution to the rust-lld executable itself.

linker Copy Chapter

This flag controls which linker rustc invokes to link your code. It takes a
path to the linker executable. If this flag is not specified, the linker will
be inferred based on the target. See also the linker-flavor
flag for another way to specify the linker.

Note that on Unix-like targets (for example, *-unknown-linux-gnu or *-unknown-freebsd)
the C compiler (for example cc or clang) is used as the "linker" here, serving as a linker driver.
It will invoke the actual linker with all the necessary flags to be able to link against the system libraries like libc.

linker-features Copy Chapter

The -Clinker-features flag allows enabling or disabling specific features used during linking.

These feature flags are a flexible extension mechanism that is complementary to linker flavors,
designed to avoid the combinatorial explosion of having to create a new set of flavors for each
linker feature we'd want to use.

The flag accepts a comma-separated list of features, individually enabled (+feature) or disabled
(-feature).

Currently only one is stable, and only on the x86_64-unknown-linux-gnu target:

• lld: to toggle trying to use the lld linker, either the system-installed binary, or the self-contained
  rust-lld linker (via the -Clink-self-contained=+linker flag).

For example, use:

• -Clinker-features=+lld to opt into using the lld linker, when possible (see the Implementation notes below)
• -Clinker-features=-lld to opt out instead, for targets where it is configured as the default linker

Note that only the -lld opt-out is stable on the x86_64-unknown-linux-gnu target: +lld is
already the default on this target.

Implementation notes

On the x86_64-unknown-linux-gnu target, when using the default linker flavor (using cc as the
linker driver), rustc will try to use lld by passing a -fuse-ld=lld link argument to the driver.
rustc will also try to detect if that causes an error during linking (for example, if GCC is too
old to understand the flag, and returns an error) and will then retry linking without this argument,
as a fallback.

If the user also passes a -Clink-arg=-fuse-ld=$value, both will be given to the linker
driver but the user's will be passed last, and would generally have priority over rustc's.

linker-flavor Copy Chapter

This flag controls the linker flavor used by rustc. If a linker is given with
the -C linker flag, then the linker flavor is inferred from the
value provided. If no linker is given then the linker flavor is used to
determine the linker to use. Every rustc target defaults to some linker
flavor. Valid options are:

• em: use Emscripten emcc.
• gcc: use the cc executable, which is typically gcc or clang on many systems.
• ld: use the ld executable.
• msvc: use the link.exe executable from Microsoft Visual Studio MSVC.
• wasm-ld: use the wasm-ld
  executable, a port of LLVM lld for WebAssembly.
• ld64.lld: use the LLVM lld executable with the -flavor darwin
  flag for Apple's ld.
• ld.lld: use the LLVM lld executable with the -flavor gnu
  flag for GNU binutils' ld.
• lld-link: use the LLVM lld executable with the -flavor link
  flag for Microsoft's link.exe.

linker-plugin-lto Copy Chapter

This flag defers LTO optimizations to the linker. See
linker-plugin-LTO for more details. It takes one of
the following values:

• y, yes, on, true or no value: enable linker plugin LTO.
• n, no, off or false: disable linker plugin LTO (the default).
• A path to the linker plugin.

More specifically this flag will cause the compiler to replace its typical
object file output with LLVM bitcode files. For example an rlib produced with
-Clinker-plugin-lto will still have *.o files in it, but they'll all be LLVM
bitcode instead of actual machine code. It is expected that the native platform
linker is capable of loading these LLVM bitcode files and generating code at
link time (typically after performing optimizations).

Note that rustc can also read its own object files produced with
-Clinker-plugin-lto. If an rlib is only ever going to get used later with a
-Clto compilation then you can pass -Clinker-plugin-lto to speed up
compilation and avoid generating object files that aren't used.

llvm-args Copy Chapter

This flag can be used to pass a list of arguments directly to LLVM.

The list must be separated by spaces.

Pass --help to see a list of options.

Because this flag directly talks to LLVM, it is not subject to the usual stability guarantees of rustc's CLI interface.

lto Copy Chapter

This flag controls whether LLVM uses link time
optimizations to produce
better optimized code, using whole-program analysis, at the cost of longer
linking time. It takes one of the following values:

• y, yes, on, true, fat, or no value: perform "fat" LTO which attempts to
  perform optimizations across all crates within the dependency graph.
• thin: perform "thin"
  LTO.
  This is similar to "fat", but takes substantially less time to run while
  still achieving performance gains similar to "fat".
  For larger projects like the Rust compiler, ThinLTO can even result in better performance than fat LTO.
• n, no, off, false: disables LTO.

If -C lto is not specified, then the compiler will attempt to perform "thin
local LTO" which performs "thin" LTO on the local crate only across its
codegen units. When -C lto is not specified, LTO is
disabled if codegen units is 1 or optimizations are disabled (-C opt-level=0). That is:

• When -C lto is not specified:
  • codegen-units=1: disable LTO.
  • opt-level=0: disable LTO.
• When -C lto is specified:
  • lto: 16 codegen units, perform fat LTO across crates.
  • codegen-units=1 + lto: 1 codegen unit, fat LTO across crates.

See also linker-plugin-lto for cross-language LTO.

metadata Copy Chapter

This option allows you to control the metadata used for symbol mangling. This
takes a space-separated list of strings. Mangled symbols will incorporate a
hash of the metadata. This may be used, for example, to differentiate symbols
between two different versions of the same crate being linked.

no-prepopulate-passes Copy Chapter

This flag tells the pass manager to use an empty list of passes, instead of the
usual pre-populated list of passes.

When combined with -O --emit llvm-ir, it can be used to see the optimized LLVM IR emitted by rustc before any optimizations are applied by LLVM.

no-redzone Copy Chapter

This flag allows you to disable the
red zone. It takes one
of the following values:

• y, yes, on, true or no value: disable the red zone.
• n, no, off or false: enable the red zone.

The default behaviour, if the flag is not specified, depends on the target.

no-vectorize-loops Copy Chapter

This flag disables loop
vectorization.

no-vectorize-slp Copy Chapter

This flag disables vectorization using
superword-level
parallelism.

opt-level Copy Chapter

This flag controls the optimization level.

• 0: no optimizations, also turns on
  cfg(debug_assertions) (the default).
• 1: basic optimizations.
• 2: some optimizations.
• 3: all optimizations.
• s: optimize for binary size.
• z: optimize for binary size, but more aggressively. Often results in larger binaries than s

Note: The -O flag is an alias for -C opt-level=3.

The default is 0.

overflow-checks Copy Chapter

This flag allows you to control the behavior of runtime integer
overflow. When
overflow-checks are enabled, a panic will occur on overflow. This flag takes
one of the following values:

• y, yes, on, true or no value: enable overflow checks.
• n, no, off or false: disable overflow checks.

If not specified, overflow checks are enabled if
debug-assertions are enabled, disabled otherwise.

panic Copy Chapter

This option lets you control what happens when the code panics.

• abort: terminate the process upon panic
• immediate-abort: terminate the process upon panic, and do not call any panic hooks
• unwind: unwind the stack upon panic

If not specified, the default depends on the target.

If any crate in the crate graph uses abort, the final binary (bin, dylib, cdylib, staticlib) must also use abort.
If any crate in the crate graph uses immediate-abort, every crate in the graph must use immediate-abort.
If std is used as a dylib with unwind, the final binary must also use unwind.

passes Copy Chapter

This flag can be used to add extra LLVM
passes to the compilation.

The list must be separated by spaces.

See also the no-prepopulate-passes flag.

Because this flag directly talks to LLVM, it not subject to the usual stability guarantees of rustc's CLI interface.

prefer-dynamic Copy Chapter

By default, rustc prefers to statically link dependencies. This option will
indicate that dynamic linking should be used if possible if both a static and
dynamic versions of a library are available.

There is an internal algorithm
for determining whether or not it is possible to statically or dynamically link
with a dependency.

This flag takes one of the following values:

• y, yes, on, true or no value: prefer dynamic linking.
• n, no, off or false: prefer static linking (the default).

profile-generate Copy Chapter

This flag allows for creating instrumented binaries that will collect
profiling data for use with profile-guided optimization (PGO). The flag takes
an optional argument which is the path to a directory into which the
instrumented binary will emit the collected data. See the chapter on
profile-guided optimization for more information.

profile-sample-use Copy Chapter

This flag specifies the profiling data file to be used for sample-based
profile-guided optimization (SPGO). The flag takes a mandatory argument which
is the path to a valid .prof file. See the chapter on
profile-guided optimization for more information.
The -Zdebuginfo-for-profiling can be used to improve the quality of the
profiling data.

profile-use Copy Chapter

This flag specifies the profiling data file to be used for profile-guided
optimization (PGO). The flag takes a mandatory argument which is the path
to a valid .profdata file. See the chapter on
profile-guided optimization for more information.

relocation-model Copy Chapter

This option controls generation of
position-independent code (PIC).

Supported values for this option are:

Primary relocation models

• static - non-relocatable code, machine instructions may use absolute addressing modes.

• pic - fully relocatable position independent code,
  machine instructions need to use relative addressing modes.
  Equivalent to the "uppercase" -fPIC or -fPIE options in other compilers,
  depending on the produced crate types.
  This is the default model for majority of supported targets.

• pie - position independent executable, relocatable code but without support for symbol
  interpositioning (replacing symbols by name using LD_PRELOAD and similar). Equivalent to the "uppercase" -fPIE option in other compilers. pie
  code cannot be linked into shared libraries (you'll get a linking error on attempt to do this).

Special relocation models

• dynamic-no-pic - relocatable external references, non-relocatable code.
  Only makes sense on Darwin and is rarely used.
  If StackOverflow tells you to use this as an opt-out of PIC or PIE, don't believe it,
  use -C relocation-model=static instead.
• ropi, rwpi and ropi-rwpi - relocatable code and read-only data, relocatable read-write data,
  and combination of both, respectively.
  Only makes sense for certain embedded ARM targets.
• default - relocation model default to the current target.
  Only makes sense as an override for some other explicitly specified relocation model
  previously set on the command line.

Supported values can also be discovered by running rustc --print relocation-models.

Linking effects

In addition to codegen effects, relocation-model has effects during linking.

If the relocation model is pic and the current target supports position-independent executables
(PIE), the linker will be instructed (-pie) to produce one.
If the target doesn't support both position-independent and statically linked executables,
then -C target-feature=+crt-static "wins" over -C relocation-model=pic,
and the linker is instructed (-static) to produce a statically linked
but not position-independent executable.

relro-level Copy Chapter

This flag controls what level of RELRO (Relocation Read-Only) is enabled. RELRO is an exploit
mitigation which makes the Global Offset Table (GOT) read-only.

Supported values for this option are:

• off: Dynamically linked functions are resolved lazily and the GOT is writable.
• partial: Dynamically linked functions are resolved lazily and written into the Procedure
  Linking Table (PLT) part of the GOT (.got.plt). The non-PLT part of the GOT (.got) is made
  read-only and both are moved to prevent writing from buffer overflows.
• full: Dynamically linked functions are resolved at the start of program execution and the
  Global Offset Table (.got/.got.plt) is populated eagerly and then made read-only. The GOT is
  also moved to prevent writing from buffer overflows. Full RELRO uses more memory and increases
  process startup time.

This flag is ignored on platforms where RELRO is not supported (targets which do not use the ELF
binary format), such as Windows or macOS. Each rustc target has its own default for RELRO. rustc
enables Full RELRO by default on platforms where it is supported.

remark Copy Chapter

This flag lets you print remarks for optimization passes.

The list of passes should be separated by spaces.

all will remark on every pass.

rpath Copy Chapter

This flag controls whether rustc sets an rpath for the binary.
It takes one of the following values:

• y, yes, on, true or no value: enable rpath.
• n, no, off or false: disable rpath (the default).

This flag only does something on Unix-like platforms (Mach-O and ELF), it is ignored on other platforms.

If enabled, rustc will add output-relative (using @load_path on Mach-O and $ORIGIN on ELF respectively) rpaths to all dylib dependencies.

For example, for the following directory structure, with libdep.so being a dylib crate compiled with -Cprefer-dynamic:

dep
 |- libdep.so
a.rs

rustc a.rs --extern dep=dep/libdep.so -Crpath will, on x86-64 Linux, result in approximately the following DT_RUNPATH: $ORIGIN/dep:$ORIGIN/$RELATIVE_PATH_TO_SYSROOT/lib/rustlib/x86_64-unknown-linux-gnu/lib (where RELATIVE_PATH_TO_SYSROOT depends on the build directory location).

This is primarily useful for local development, to ensure that all the dylib dependencies can be found appropriately.

To set the rpath to a different value (which can be useful for distribution), -Clink-arg with a platform-specific linker argument can be used to set the rpath directly.

save-temps Copy Chapter

This flag controls whether temporary files generated during compilation are
deleted once compilation finishes. It takes one of the following values:

• y, yes, on, true or no value: save temporary files.
• n, no, off or false: delete temporary files (the default).

split-debuginfo Copy Chapter

This option controls the emission of "split debuginfo" for debug information
that rustc generates. The default behavior of this option is
platform-specific, and not all possible values for this option work on all
platforms. Possible values are:

• off - This is the default for platforms with ELF binaries and windows-gnu
  (not Windows MSVC and not macOS). This typically means that DWARF debug
  information can be found in the final artifact in sections of the executable.
  This option is not supported on Windows MSVC. On macOS this options prevents
  the final execution of dsymutil to generate debuginfo.

• packed - This is the default for Windows MSVC and macOS. The term
  "packed" here means that all the debug information is packed into a separate
  file from the main executable. On Windows MSVC this is a *.pdb file, on
  macOS this is a *.dSYM folder, and on other platforms this is a *.dwp
  file.

• unpacked - This means that debug information will be found in separate
  files for each compilation unit (object file). This is not supported on
  Windows MSVC. On macOS this means the original object files will contain
  debug information. On other Unix platforms this means that *.dwo files will
  contain debug information.

Note that all three options are supported on Linux and Apple platforms,
packed is supported on Windows-MSVC, and all other platforms support off.
Attempting to use an unsupported option requires using the nightly channel
with the -Z unstable-options flag.

strip Copy Chapter

The option -C strip=val controls stripping of debuginfo and similar auxiliary
data from binaries during linking.

Supported values for this option are:

• none - debuginfo and symbols are not modified.
• debuginfo - debuginfo sections and debuginfo symbols from the symbol table
  section are stripped at link time and are not copied to the produced binary.
  This should leave backtraces mostly-intact but may make using a debugger like
  gdb or lldb ineffectual. Prior to 1.79, this unintentionally disabled the
  generation of *.pdb files on MSVC, resulting in the absence of symbols.
• symbols - same as debuginfo, but the rest of the symbol table section is
  stripped as well, depending on platform support. On platforms which depend on
  this symbol table for backtraces, profiling, and similar, this can affect
  them so negatively as to make the trace incomprehensible. Programs which may
  be combined with others, such as CLI pipelines and developer tooling, or even
  anything which wants crash-reporting, should usually avoid -Cstrip=symbols.

Note that, at any level, removing debuginfo only necessarily impacts "friendly"
introspection. -Cstrip cannot be relied on as a meaningful security or
obfuscation measure, as disassemblers and decompilers can extract considerable
information even in the absence of symbols.

symbol-mangling-version Copy Chapter

This option controls the name mangling format for encoding Rust item names
for the purpose of generating object code and linking.

Supported values for this option are:

• v0 — The "v0" mangling scheme.

The default, if not specified, will use a compiler-chosen default which may
change in the future.

See the Symbol Mangling chapter for details on symbol mangling and the mangling format.

target-cpu Copy Chapter

This instructs rustc to generate code specifically for a particular processor.

You can run rustc --print target-cpus to see the valid options to pass
and the default target CPU for the current build target.
Each target has a default base CPU. Special values include:

• native can be passed to use the processor of the host machine.
• generic refers to an LLVM target with minimal features but modern tuning.

target-feature Copy Chapter

Individual targets will support different features; this flag lets you control
enabling or disabling a feature. Each feature should be prefixed with a + to
enable it or - to disable it.

Features from multiple -C target-feature options are combined.
Multiple features can be specified in a single option by separating them
with commas - -C target-feature=+x,-y.
If some feature is specified more than once with both + and -,
then values passed later override values passed earlier.
For example, -C target-feature=+x,-y,+z -Ctarget-feature=-x,+y
is equivalent to -C target-feature=-x,+y,+z.

To see the valid options and an example of use, run rustc --print target-features.

Using this flag is unsafe and might result in undefined runtime
behavior.

See also the target_feature
attribute
for controlling features per-function.

This also supports the feature +crt-static and -crt-static to control
static C runtime linkage.

Each target and target-cpu has a default set of enabled
features.

tune-cpu Copy Chapter

This instructs rustc to schedule code specifically for a particular
processor. This does not affect the compatibility (instruction sets or ABI),
but should make your code slightly more efficient on the selected CPU.

The valid options are the same as those for target-cpu.
The default is None, which LLVM translates as the target-cpu.

This is an unstable option. Use -Z tune-cpu=machine to specify a value.

Due to limitations in LLVM (12.0.0-git9218f92), this option is currently
effective only for x86 targets.

Src Doc Rustc Src Lints Index (`src/doc/rustc/src/lints/index.md`) Copy Section

Lints

In software, a "lint" is a tool used to help improve your source code. The
Rust compiler contains a number of lints, and when it compiles your code, it will
also run the lints. These lints may produce a warning, an error, or nothing at all,
depending on how you've configured things.

Here's a small example:

$ cat main.rs
fn main() {
    let x = 5;
}
$ rustc main.rs
warning: unused variable: `x`
 --> main.rs:2:9
  |
2 |     let x = 5;
  |         ^
  |
  = note: `#[warn(unused_variables)]` on by default
  = note: to avoid this warning, consider using `_x` instead

This is the unused_variables lint, and it tells you that you've introduced
a variable that you don't use in your code. That's not wrong, so it's not
an error, but it might be a bug, so you get a warning.

Future-incompatible lints Copy Chapter

Sometimes the compiler needs to be changed to fix an issue that can cause
existing code to stop compiling. "Future-incompatible" lints are issued in
these cases to give users of Rust a smooth transition to the new behavior.
Initially, the compiler will continue to accept the problematic code and issue
a warning. The warning has a description of the problem, a notice that this
will become an error in the future, and a link to a tracking issue that
provides detailed information and an opportunity for feedback. This gives
users some time to fix the code to accommodate the change. After some time,
the warning may become an error.

The following is an example of what a future-incompatible looks like:

warning: borrow of packed field is unsafe and requires unsafe function or block (error E0133)
  --> lint_example.rs:11:13
   |
11 |     let y = &x.data.0;
   |             ^^^^^^^^^
   |
   = note: `#[warn(safe_packed_borrows)]` on by default
   = warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
   = note: for more information, see issue #46043 <https://github.com/rust-lang/rust/issues/46043>
   = note: fields of packed structs might be misaligned: dereferencing a misaligned pointer or even just creating a misaligned reference is undefined behavior

For more information about the process and policy of future-incompatible
changes, see RFC 1589.

Src Doc Rustc Src Symbol Mangling Index (`src/doc/rustc/src/symbol-mangling/index.md`) Copy Section

Symbol Mangling

Symbol name mangling is used by rustc to encode a unique name for symbols that are used during code generation.
The encoded names are used by the linker to associate the name with the thing it refers to.

The method for mangling the names can be controlled with the -C symbol-mangling-version option.

Per-item control Copy Chapter

The #[no_mangle] attribute can be used on items to disable name mangling on that item.

The #[export_name]attribute can be used to specify the exact name that will be used for a function or static.

Items listed in an extern block use the identifier of the item without mangling to refer to the item.
The #[link_name] attribute can be used to change that name.

WebAssembly import modules Copy Section

On WebAssembly targets, foreign items in extern blocks can use the same import name without
conflicting when they use different #[link(wasm_import_module = "...")]
values.

Decoding Copy Chapter

The encoded names may need to be decoded in some situations.
For example, debuggers and other tooling may need to demangle the name so that it is more readable to the user.
Recent versions of gdb and lldb have built-in support for demangling Rust identifiers.
In situations where you need to do your own demangling, the rustc-demangle crate can be used to programmatically demangle names.
rustfilt is a CLI tool which can demangle names.

An example of running rustfilt:

$ rustfilt _RNvCskwGfYPst2Cb_3foo16example_function
foo::example_function

Mangling versions Copy Chapter

There is currently one stable mangling scheme version - v0. On nightly builds, rustc supports
switching back to the legacy mangling scheme using -C symbol-mangling-version. The v0
mangling scheme is described in the v0 Symbol Format chapter.

Src Doc Rustc Src Targets Index (`src/doc/rustc/src/targets/index.md`) Copy Section

Targets

rustc is a cross-compiler by default. This means that you can use any compiler to build for any
architecture. The list of targets are the possible architectures that you can build for. See
the Platform Support page for a detailed list of targets, or
Built-in Targets for instructions on how to view what is available for your version
of rustc.

To see all the options that you can set with a target, see the docs
here.

To compile to a particular target, use the --target flag:

$ rustc src/main.rs --target=wasm32-unknown-unknown

Target Features Copy Chapter

x86, and ARMv8 are two popular CPU architectures. Their instruction sets form a common baseline across most CPUs. However, some CPUs extend these with custom instruction sets, e.g. vector (AVX), bitwise manipulation (BMI) or cryptographic (AES).

Developers, who know on which CPUs their compiled code is going to run can choose to add (or remove) CPU specific instruction sets via the -C target-feature=val flag.

Please note, that this flag is generally considered as unsafe. More details can be found in this section.

Src Doc Rustc Src Tests Index (`src/doc/rustc/src/tests/index.md`) Copy Section

Tests

rustc has a built-in facility for building and running tests for a crate.
More information about writing and running tests may be found in the Testing
Chapter of the Rust Programming Language book.

Tests are written as free functions with the #[test]
attribute. For example:

#[test]
fn it_works() {
    assert_eq!(2 + 2, 4);
}

Tests "pass" if they return without an error. They "fail" if they panic, or
return a type such as Result that implements the Termination trait
with a non-zero value.

By passing the --test option to rustc, the compiler will build the crate
in a special mode to construct an executable that will run the tests in the
crate. The --test flag will make the following changes:

• The crate will be built as a bin crate type, forcing it to be an
  executable.
• Links the executable with libtest, the test harness that is part of the
  standard library, which handles running the tests.
• Synthesizes a main function which will process command-line arguments
  and run the tests. This new main function will replace any existing main
  function as the entry point of the executable, though the existing main
  will still be compiled.
• Enables the test cfg option, which allows your code to use conditional
  compilation to detect if it is being built as a test.
• Enables building of functions annotated with the test
  and bench attributes, which will be run by the test
  harness.

After the executable is created, you can run it to execute the tests and
receive a report on what passes and fails. If you are using Cargo to manage
your project, it has a built-in cargo test command which handles all of
this automatically. An example of the output looks like this:

running 4 tests
test it_works ... ok
test check_valid_args ... ok
test invalid_characters ... ok
test walks_the_dog ... ok

test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

Note: Tests must be built with the unwind panic
strategy. This is because all tests run in the same
process, and they are intended to catch panics, which is not possible with
the abort strategy. See the unstable -Z panic-abort-tests option for
experimental support of the abort strategy by spawning tests in separate
processes.

Test attributes Copy Chapter

Tests are indicated using attributes on free functions. The following
attributes are used for testing, see the linked documentation for more
details:

• #[test] — Indicates a function is a test to be run.
• #[bench] — Indicates a function is a benchmark to be
  run. Benchmarks are currently unstable and only available in the nightly
  channel, see the unstable docs for more details.
• #[should_panic] — Indicates that the test
  function will only pass if the function panics.
• #[ignore] — Indicates that the test function will be
  compiled, but not run by default. See the --ignored and
  --include-ignored options to run these tests.

CLI arguments Copy Chapter

The libtest harness has several command-line arguments to control its
behavior.

Note: When running with cargo test, the libtest CLI arguments must be
passed after the -- argument to differentiate between flags for Cargo and
those for the harness. For example: cargo test -- --no-capture

Filters Copy Section

Positional arguments (those without a - prefix) are treated as filters which
will only run tests whose name matches one of those strings. The filter will
match any substring found in the full path of the test function. For example,
if the test function it_works is located in the module
utils::paths::tests, then any of the filters works, path, utils::, or
utils::paths::tests::it_works will match that test.

See Selection options for more options to control which
tests are run.

Action options Copy Section

The following options perform different actions other than running tests.

`--list`

Prints a list of all tests and benchmarks. Does not run any of the tests.
Filters can be used to list only matching tests.

`-h`, `--help`

Displays usage information and command-line options.

Selection options Copy Section

The following options change how tests are selected.

`--test`

This is the default mode where all tests will be run as well as running all
benchmarks with only a single iteration (to ensure the benchmark works,
without taking the time to actually perform benchmarking). This can be
combined with the --bench flag to run both tests and perform full
benchmarking.

`--bench`

This runs in a mode where tests are ignored, and only runs benchmarks. This
can be combined with --test to run both benchmarks and tests.

`--exact`

This forces filters to match the full path of the test exactly.
For example, if the test it_works is in the module utils::paths::tests,
then only the string utils::paths::tests::it_works will match that test.

`--skip` _FILTER_

Skips any tests whose name contains the given FILTER string. This flag may
be passed multiple times.

`--ignored`

Runs only tests that are marked with the ignore
attribute.

`--include-ignored`

Runs both ignored and non-ignored tests.

`--exclude-should-panic`

Excludes tests marked with the should_panic
attribute.

⚠️ 🚧 This option is unstable, and requires the -Z unstable-options flag. See tracking issue
#82348 for more information.

Execution options Copy Section

The following options affect how tests are executed.

`--fail-fast`

Stops tests after the first failure.

If running tests in parallel (which is the default), then tests that have already been started on
other threads will be allowed to run to completion before the process exits.

Note that when running tests in parallel, the test execution order is non-deterministic:
if multiple tests would fail, the first failure encountered will be reported.

⚠️ 🚧 This requires the -Z unstable-options flag.

`--test-threads` _NUM_THREADS_

Sets the number of threads to use for running tests in parallel. By default,
uses the amount of concurrency available on the hardware as indicated by
available_parallelism.

Deprecated: this can also be specified with the RUST_TEST_THREADS environment variable.

`--force-run-in-process`

Forces the tests to run in a single process when using the abort panic
strategy.

⚠️ 🚧 This only works with the unstable -Z panic-abort-tests option, and
requires the -Z unstable-options flag. See tracking issue
#67650 for more information.

`--ensure-time`

⚠️ 🚧 This option is unstable, and requires the -Z unstable-options flag. See tracking issue
#64888 and the unstable
docs for more information.

`--shuffle`

Runs the tests in random order, as opposed to the default alphabetical order.

Deprecated: this may also be specified by setting the RUST_TEST_SHUFFLE environment
variable to anything but 0.

The random number generator seed that is output can be passed to
--shuffle-seed to run the tests in the same order
again.

Note that --shuffle does not affect whether the tests are run in parallel. To
run the tests in random order sequentially, use --shuffle --test-threads 1.

⚠️ 🚧 This option is unstable, and requires the -Z unstable-options flag. See tracking issue
#89583 for more information.

`--shuffle-seed` _SEED_

Like --shuffle, but seeds the random number generator with
SEED. Thus, calling the test harness with --shuffle-seed SEED twice runs
the tests in the same order both times.

SEED is any 64-bit unsigned integer, for example, one produced by
--shuffle.

Deprecated: this can also be specified with the RUST_TEST_SHUFFLE_SEED environment
variable.

⚠️ 🚧 This option is unstable, and requires the -Z unstable-options flag. See tracking issue
#89583 for more information.

Output options Copy Section

The following options affect the output behavior.

`-q`, `--quiet`

Displays one character per test instead of one line per test. This is an alias
for --format=terse.

`--no-capture`

Does not capture the stdout and stderr of the test, and allows tests to print
to the console. Usually the output is captured, and only displayed if the test
fails.

Deprecated: this may also be specified by setting the RUST_TEST_NOCAPTURE environment
variable to anything but 0.

--nocapture is a deprecated alias for --no-capture.

`--show-output`

Displays the stdout and stderr of successful tests after all tests have run.

Contrast this with --no-capture which allows tests to print
while they are running, which can cause interleaved output if there are
multiple tests running in parallel, --show-output ensures the output is
contiguous, but requires waiting for all tests to finish.

`--color` _COLOR_

Control when colored terminal output is used. Valid options:

• auto: Colorize if stdout is a tty and --no-capture is not
  used. This is the default.
• always: Always colorize the output.
• never: Never colorize the output.

`--format` _FORMAT_

Controls the format of the output. Valid options:

• pretty: This is the default format, with one line per test.
• terse: Displays only a single character per test. --quiet
  is an alias for this option.
• json: Emits JSON objects, one per line. ⚠️ 🚧 This option is
  unstable, and requires the -Z unstable-options flag.
  See tracking issue #49359
  for more information.

`--logfile` _PATH_

Writes the results of the tests to the given file.

This option is deprecated.

`--report-time`

⚠️ 🚧 This option is unstable, and requires the -Z unstable-options flag. See tracking issue
#64888 and the unstable
docs for more information.

Unstable options Copy Section

Some CLI options are added in an "unstable" state, where they are intended for
experimentation and testing to determine if the option works correctly, has
the right design, and is useful. The option may not work correctly, break, or
change at any time. To signal that you acknowledge that you are using an
unstable option, they require passing the -Z unstable-options command-line
flag.

Benchmarks Copy Chapter

The libtest harness supports running benchmarks for functions annotated with
the #[bench] attribute. Benchmarks are currently unstable, and only
available on the nightly channel. More information may be found in the
unstable book.

Custom test frameworks Copy Chapter

Experimental support for using custom test harnesses is available on the
nightly channel. See tracking issue
#50297 and the
custom_test_frameworks documentation for more information.

Src Tools Rust Analyzer Docs Book README (`src/tools/rust-analyzer/docs/book/README.md`) Copy Section

rust-analyzer documentation

The rust analyzer manual uses mdbook.

Quick start Copy Chapter

To run the documentation site locally:

cargo install --locked mdbook
cargo xtask codegen
cd docs/book
mdbook serve
# make changes to documentation files in doc/book/src
# ...

mdbook will rebuild the documentation as changes are made.

Making updates Copy Chapter

While not required, installing the mdbook binary can be helpful in order to see the changes.
Start with the mdbook User Guide to familiarize yourself with the tool.

Generated documentation Copy Chapter

Four sections are generated dynamically: assists, configuration, diagnostics and features. Their content is found in the generated.md files
of the respective book section, for example src/configuration_generated.md, and are included in the book via mdbook's
include functionality. Generated files can be rebuilt by running the various
test cases that generate them, or by simply running all of the rust-analyzer tests with cargo test and cargo xtask codegen.

Src Doc Rustc Dev Guide Src Building Bootstrapping Intro (`src/doc/rustc-dev-guide/src/building/bootstrapping/intro.md`) Copy Section

Bootstrapping the compiler

Bootstrapping is the process of using a compiler to compile itself.
More accurately, it means using an older compiler to compile a newer version of the same compiler.

This raises a chicken-and-egg paradox: where did the first compiler come from?
It must have been written in a different language.
In Rust's case, it was written in OCaml.
However, it was abandoned long ago, and the
only way to build a modern version of rustc is with a slightly less modern version.

This is exactly how Rust's bootstrap build system works: it downloads the current beta release of
rustc, then uses it to compile the new compiler.

In this section, we give a high-level overview of
what Bootstrap does, followed by a high-level
introduction to how Bootstrap does it.

Additionally, see debugging bootstrap to learn about debugging methods.

Src Doc Rustc Dev Guide Src Tests Codegen Backend Tests Intro (`src/doc/rustc-dev-guide/src/tests/codegen-backend-tests/intro.md`) Copy Section

Codegen backend testing

See also the Code generation chapter.

In addition to the primary LLVM codegen backend, the rust-lang/rust CI also runs tests of the cranelift and GCC codegen backends in certain test jobs.

For more details on the tests involved, see:

• Cranelift codegen backend tests
• GCC codegen backend tests

Src Doc Rustc Src Lints Listing Index (`src/doc/rustc/src/lints/listing/index.md`) Copy Section

Lint Listing

This section lists out all of the lints, grouped by their default lint levels.

You can also see this list by running rustc -W help.

Src Tools Rust Analyzer Docs Book Src README (`src/tools/rust-analyzer/docs/book/src/README.md`) Copy Section

rust-analyzer

rust-analyzer is a language server that provides IDE functionality for
writing Rust programs. You can use it with any editor that supports
the Language Server
Protocol (VS
Code, Vim, Emacs, Zed, etc).

rust-analyzer features include go-to-definition, find-all-references,
refactorings and code completion. rust-analyzer also supports
integrated formatting (with rustfmt) and integrated diagnostics (with
rustc and clippy).

Internally, rust-analyzer is structured as a set of libraries for
analyzing Rust code. See
Architecture
for more details.

To improve this document, send a pull request:
https://github.com/rust-lang/rust-analyzer

The manual is written in markdown and includes
some extra files which are generated from the source code. Run
cargo test and cargo xtask codegen to create these.

If you have questions about using rust-analyzer, please ask them in the
"IDEs and Editors" topic of Rust
users forum.

Src Tools Rust Analyzer Docs Book Src Contributing README (`src/tools/rust-analyzer/docs/book/src/contributing/README.md`) Copy Section

Contributing Quick Start

rust-analyzer is an ordinary Rust project, which is organized as a Cargo workspace, builds on stable and doesn't depend on C libraries.
So, just

cargo test

should be enough to get you started!

To learn more about how rust-analyzer works, see Architecture.
It also explains the high-level layout of the source code.
Do skim through that document.

We also publish rustdoc docs to https://rust-lang.github.io/rust-analyzer/ide/.
Note though, that the internal documentation is very incomplete.

Various organizational and process issues are discussed in this document.

Getting in Touch

rust-analyzer is a part of the RLS-2.0 working
group.
Discussion happens in this Zulip stream:

https://rust-lang.zulipchat.com/#narrow/stream/185405-t-compiler.2Frust-analyzer

Issue Labels

• good-first-issue
  are good issues to get into the project.
• E-has-instructions
  issues have links to the code in question and tests.
• Broken Window
  are issues which are not necessarily critical by themselves, but which should be fixed ASAP regardless, to avoid accumulation of technical debt.
• E-easy,
  E-medium,
  E-hard,
  E-unknown,
  labels are estimates for how hard would be to write a fix. Each triaged issue should have one of these labels.
• S-actionable and
  S-unactionable
  specify if there are concrete steps to resolve or advance an issue. Roughly, actionable issues need only work to be fixed,
  while unactionable ones are blocked either on user feedback (providing a reproducible example), or on larger architectural
  work or decisions. This classification is descriptive, not prescriptive, and might be wrong: Any unactionable issue might have a simple fix that we missed.
  Each triaged issue should have one of these labels.
• fun
  is for cool, but probably hard stuff.
• C-Architecture
  is for moderate/large scale architecture discussion.
  Also a kind of fun.
  These issues should generally include a link to a Zulip discussion thread.

Code Style & Review Process

See the Style Guide.

Cookbook

CI Copy Chapter

We use GitHub Actions for CI.
Most of the things, including formatting, are checked by cargo test.
If cargo test passes locally, that's a good sign that CI will be green as well.
The only exception is that some long-running tests are skipped locally by default.
Use env RUN_SLOW_TESTS=1 cargo test to run the full suite.

We use bors to enforce the not rocket science rule.

Launching rust-analyzer Copy Chapter

Debugging the language server can be tricky.
LSP is rather chatty, so driving it from the command line is not really feasible, driving it via VS Code requires interacting with two processes.

For this reason, the best way to see how rust-analyzer works is to find a relevant test and execute it.
VS Code & Emacs include an action for running a single test.

Launching a VS Code instance with a locally built language server is also possible.
There's "Run Extension (Debug Build)" launch configuration for this in VS Code.

In general, I use one of the following workflows for fixing bugs and implementing features:

If the problem concerns only internal parts of rust-analyzer (i.e. I don't need to touch the rust-analyzer crate or TypeScript code), there is a unit-test for it.
So, I use rust-analyzer: Run action in VS Code to run this single test, and then just do printf-driven development/debugging.
As a sanity check after I'm done, I use cargo xtask install --server and Reload Window action in VS Code to verify that the thing works as I expect.

If the problem concerns only the VS Code extension, I use Run Installed Extension launch configuration from launch.json.
Notably, this uses the usual rust-analyzer binary from PATH.
For this, it is important to have the following in your settings.json file:

{
    "rust-analyzer.server.path": "rust-analyzer"
}

After I am done with the fix, I use cargo xtask install --client to try the new extension for real.

If I need to fix something in the rust-analyzer crate, I feel sad because it's on the boundary between the two processes, and working there is slow.
I usually just cargo xtask install --server and poke changes from my live environment.
Note that this uses --release, which is usually faster overall, because loading stdlib into debug version of rust-analyzer takes a lot of time.
To speed things up, sometimes I open a temporary hello-world project which has "rust-analyzer.cargo.sysroot": null in .code/settings.json.
This flag causes rust-analyzer to skip loading the sysroot, which greatly reduces the amount of things rust-analyzer needs to do, and makes printf's more useful.
Note that you should only use the eprint! family of macros for debugging: stdout is used for LSP communication, and print! would break it.

If I need to fix something simultaneously in the server and in the client, I feel even more sad.
I don't have a specific workflow for this case.

Additionally, I use cargo run --release -p rust-analyzer -- analysis-stats path/to/some/rust/crate to run a batch analysis.
This is primarily useful for performance optimizations, or for bug minimization.

TypeScript Tests Copy Chapter

If you change files under editors/code and would like to run the tests and linter, install npm and run:

cd editors/code
npm ci
npm run lint

How to ... Copy Chapter

• ... add an assist? #7535
• ... add a new protocol extension? #4569
• ... add a new configuration option? #7451
• ... add a new completion? #6964
• ... allow new syntax in the parser? #7338

Logging Copy Chapter

Logging is done by both rust-analyzer and VS Code, so it might be tricky to figure out where logs go.

Inside rust-analyzer, we use the tracing crate for logging,
and tracing-subscriber for logging frontend.
By default, log goes to stderr, but the stderr itself is processed by VS Code.
--log-file CLI argument allows logging to file.
Setting the RA_LOG_FILE= environment variable will also log to file, it will also override --log-file.

To see the server stderr output in the running VS Code instance, go to the "Output" tab of the panel
and select rust-analyzer Language Server.
This shows eprintln! as well.
Note that stdout is used by LSP messages, so using println!—or anything that writes to stdout—will break rust-analyzer!

To log all communication between the server and the client, there are two choices:

• You can log on the server side, by running something like

  bash Copy

  env RA_LOG=lsp_server=debug code .

• You can log on the client side, by the rust-analyzer: Toggle LSP Logs command or enabling "rust-analyzer.trace.server": "verbose" workspace setting.
  These logs are shown in a separate tab named rust-analyzer LSP Trace in the output and could be used with LSP inspector.
  Kudos to @DJMcNab for setting this awesome infra up!

Finally there are the logs of the VSCode extension itself which go into the rust-analyzer Extension output tab.

There are also several VS Code commands which might be of interest:

• rust-analyzer: Status shows some memory-usage statistics.

• rust-analyzer: View Hir shows the HIR expressions within the function containing the cursor.

• If rust-analyzer.showSyntaxTree is enabled in settings, Rust Syntax Tree: Focus on Rust Syntax Tree View shows the syntax tree of the current file.

  You can click on nodes in the rust editor to go to the corresponding syntax node.

  You can click on Reveal Syntax Element next to a syntax node to go to the corresponding rust code and highlight the proper text range.

  If you trigger Go to Definition in the inspected Rust source file,
  the syntax tree view should scroll to and select the
  appropriate syntax node token.

  You can click on Copy next to a syntax node to copy a text representation of the node.

Profiling Copy Chapter

We have a built-in hierarchical profiler, you can enable it by using RA_PROFILE env-var:

RA_PROFILE=*             // dump everything
RA_PROFILE=foo|bar|baz   // enabled only selected entries
RA_PROFILE=*@3>10        // dump everything, up to depth 3, if it takes more than 10 ms

Some rust-analyzer contributors have export RA_PROFILE='*>10' in my shell profile.

For machine-readable JSON output, we have the RA_PROFILE_JSON env variable. We support
filtering only by span name:

RA_PROFILE=* // dump everything
RA_PROFILE_JSON="vfs_load|parallel_prime_caches|discover_command" // dump selected spans

We also have a "counting" profiler which counts number of instances of popular structs.
It is enabled by RA_COUNT=1.

To measure time for from-scratch analysis, use something like this:

cargo run --release -p rust-analyzer -- analysis-stats ../chalk/

Look for fn benchmark_xxx tests for a quick way to reproduce performance problems.

Release Process Copy Chapter

Release process is handled by release, dist, publish-release-notes and promote xtasks, release being the main one.

release assumes that you have checkouts of rust-analyzer, rust-analyzer.github.io, and rust-lang/rust in the same directory:

./rust-analyzer
./rust-analyzer.github.io
./rust-rust-analyzer  # Note the name!

The remote for rust-analyzer must be called upstream (I use origin to point to my fork).
In addition, for xtask promote (see below), rust-rust-analyzer must have a rust-analyzer remote pointing to this repository on GitHub.

release calls the GitHub API calls to scrape pull request comments and categorize them in the changelog.
This step uses the curl and jq applications, which need to be available in PATH.
Finally, you need to obtain a GitHub personal access token and set the GITHUB_TOKEN environment variable.

Release steps:

1. Set the GITHUB_TOKEN environment variable.
2. Inside rust-analyzer, run cargo xtask release. This will:
   • checkout the release branch
   • reset it to upstream/nightly
   • push it to upstream. This triggers GitHub Actions which:
     • runs cargo xtask dist to package binaries and VS Code extension
     • makes a GitHub release
     • publishes the VS Code extension to the marketplace
   • call the GitHub API for PR details
   • create a new changelog in rust-analyzer.github.io
3. While the release is in progress, fill in the changelog.
4. Commit & push the changelog.
5. Run cargo xtask publish-release-notes <CHANGELOG> -- this will convert the changelog entry in AsciiDoc to Markdown and update the body of GitHub Releases entry.
6. Tweet.
7. Perform a subtree pull.
8. Perform a subtree push.

If the GitHub Actions release fails because of a transient problem like a timeout, you can re-run the job from the Actions console.
If it fails because of something that needs to be fixed, remove the release tag (if needed), fix the problem, then start over.
Make sure to remove the new changelog post created when running cargo xtask release a second time.

We release "nightly" every night automatically and promote the latest nightly to "stable" manually, every week.

We don't do "patch" releases, unless something truly egregious comes up.
To do a patch release, cherry-pick the fix on top of the current release branch and push the branch.
There's no need to write a changelog for a patch release, it's OK to include the notes about the fix into the next weekly one.
Note: we tag releases by dates, releasing a patch release on the same day should work (by overwriting a tag), but I am not 100% sure.

Permissions Copy Chapter

There are two sets of people with extra permissions:

• The rust-lang team t-rust-analyzer.
  This team has write access to the repository and merge queue permissions (note the repo itself is managed by infra admins).
  It's ok to self-approve if you think you know what you are doing!
  Feel free to request a review or assign any PR to a reviewer with the relevant expertise to bring the work to their attention.
  Don't feel pressured to review assigned PRs though.
  If you don't feel like reviewing for whatever reason, someone else will pick the review up (but please speak up if you don't feel like it)!
• The rust-lang team t-rust-analyzer-contributors.
  This team has general triaging permissions allowing to label, close and re-open issues.

Synchronizing subtree changes Copy Chapter

rust-analyzer is a josh subtree of the rust-lang/rust
repository. We use the rustc-josh-sync tool to perform synchronization between these two
repositories. You can find documentation of the tool here.

You can install the synchronization tool using the following commands:

cargo install --locked --git https://github.com/rust-lang/josh-sync

Both pulls (synchronizing changes from rust-lang/rust into rust-analyzer) and pushes (synchronizing
changes from rust-analyzer into rust-lang/rust) are performed from this repository.
changes from rust-analyzer to rust-lang/rust) are performed from this repository.

Usually we first perform a pull, wait for it to be merged, and then perform a push.

Performing a pull Copy Section

1. Checkout a new branch that will be used to create a PR against rust-analyzer
2. Run the pull command
   text Copy

   rustc-josh-sync pull

3. Push the branch to your fork of rust-analyzer and create a PR

• If you have the gh CLI installed, rustc-josh-sync can create the PR for you.

Performing a push Copy Section

Wait for the previous pull to be merged.

1. Switch to master and pull
2. Run the push command to create a branch named `` in a rustc fork under the <gh-username> account
   text Copy

   rustc-josh-sync push <branch-name> <gh-username>

   • The push will ask you to download a checkout of the rust-lang/rust repository.
   • If you get prompted for a password, see this.
3. Create a PR from `` into rust-lang/rust

Besides the rust checkout, the Josh cache (stored under ~/.cache/rustc-josh) will contain a bare clone of rust-lang/rust. This currently takes several GBs.

Src Doc Complement Design Faq (`src/doc/complement-design-faq.md`) Copy Section

% The Rust Design FAQ

This content has moved to the website.

Src Doc Complement Lang Faq (`src/doc/complement-lang-faq.md`) Copy Section

% The Rust Language FAQ

This content has moved to the website.

Src Doc Complement Project Faq (`src/doc/complement-project-faq.md`) Copy Section

% The Rust Project FAQ

This content has moved to the website.

Src Doc Grammar (`src/doc/grammar.md`) Copy Section

% Grammar

The Rust grammar may now be found in the reference. Additionally, the grammar
working group is working on producing a testable grammar.

Src Doc Guide Crates (`src/doc/guide-crates.md`) Copy Section

% The (old) Rust Crates and Modules Guide

This content has moved into
the Rust Programming Language book.

Src Doc Guide Error Handling (`src/doc/guide-error-handling.md`) Copy Section

% Error Handling in Rust

This content has moved into
the Rust Programming Language book.

Src Doc Guide Ffi (`src/doc/guide-ffi.md`) Copy Section

% The (old) Rust Foreign Function Interface Guide

This content has moved into
the Rust Programming Language book.

Src Doc Guide Macros (`src/doc/guide-macros.md`) Copy Section

% The (old) Rust Macros Guide

This content has moved into
the Rust Programming Language book.

Src Doc Guide Ownership (`src/doc/guide-ownership.md`) Copy Section

% The (old) Rust Ownership Guide

This content has moved into
the Rust Programming Language book.

Src Doc Guide Pointers (`src/doc/guide-pointers.md`) Copy Section

% The Rust Pointer Guide

This content has been removed, with no direct replacement. Rust only
has two built-in pointer types now,
references and raw
pointers. Older Rusts had many more pointer
types, they’re gone now.

Src Doc Guide Strings (`src/doc/guide-strings.md`) Copy Section

% The (old) Guide to Rust Strings

This content has moved into
the Rust Programming Language book.

Src Doc Guide Tasks (`src/doc/guide-tasks.md`) Copy Section

% The (old) Rust Threads and Communication Guide

This content has moved into
the Rust Programming Language book.

Src Doc Guide Testing (`src/doc/guide-testing.md`) Copy Section

% The (old) Rust Testing Guide

This content has moved into
the Rust Programming Language book.

Src Doc Guide Unsafe (`src/doc/guide-unsafe.md`) Copy Section

% Writing Safe Low-level and Unsafe Code in Rust

This content has moved into
the Rust Programming Language book.

Src Doc Guide (`src/doc/guide.md`) Copy Section

% The (old) Rust Guide

This content has moved into
the Rust Programming Language book.

Src Doc Not Found (`src/doc/not_found.md`) Copy Section

% Not Found

Looks like you've taken a wrong turn.

Some things that might be helpful to you though:

Search

<fieldset id="search-from" style="display:none">
  <label> From the Standard Library</label>
  <label> From DuckDuckGo</label>
</fieldset>

Reference

• The Rust official site
• The Rust reference

Docs

The standard library

Src Doc Reference (`src/doc/reference.md`) Copy Section

% The Rust Reference has moved

We've split up the reference into chapters. Please find it at its new
home here.

Src Doc Robots (`src/doc/robots.txt`) Copy Section

User-agent: *
Disallow: /1.
Disallow: /0.
Disallow: /book/first-edition/
Disallow: /book/second-edition/
Disallow: /stable/book/first-edition/
Disallow: /stable/book/second-edition/
Disallow: /beta/book/first-edition/
Disallow: /beta/book/second-edition/
Disallow: /nightly/book/first-edition/
Disallow: /nightly/book/second-edition/

Sitemap: https://doc.rust-lang.org/sitemap.txt

Src Doc Rust (`src/doc/rust.md`) Copy Section

% The Rust Reference Manual

The manual has moved, and is now called the reference.

Src Doc Rustdoc (`src/doc/rustdoc.md`) Copy Section

% Rust Documentation

This has been moved into the rustdoc book.

Src Doc Sitemap (`src/doc/sitemap.txt`) Copy Section

https://doc.rust-lang.org/stable/
https://doc.rust-lang.org/beta/
https://doc.rust-lang.org/nightly/

Src Doc Tutorial (`src/doc/tutorial.md`) Copy Section

% The Rust Tutorial

This tutorial has been deprecated in favor of the Book, which is available free online and in dead tree form. Go check that out instead!

Compiler Rustc Codegen Cranelift Docs Dwarf (`compiler/rustc_codegen_cranelift/docs/dwarf.md`) Copy Section

Line number information

Line number information maps between machine code instructions and the source level location.

Encoding Copy Chapter

The line number information is stored in the .debug_line section for ELF and __debug_line
section of the __DWARF segment for Mach-O object files. The line number information contains a
header followed by the line program. The line program is a program for a virtual machine with
instructions like set line number for the current machine code instruction and advance the current
machine code instruction.

Tips Copy Chapter

You need to set either DW_AT_low_pc and DW_AT_high_pc or DW_AT_ranges of a
DW_TAG_compilation_unit to the range of addresses in the compilation unit. After that you need
to set DW_AT_stmt_list to the .debug_line section offset of the line program. Otherwise a
debugger won't find the line number information. On macOS the debuginfo relocations must be
section relative and not symbol relative.
See #303 (comment)
for more information.

Function debuginfo

Tips Copy Chapter

DW_TAG_subprogram requires DW_AT_name, DW_AT_low_pc and DW_AT_high_pc or DW_AT_ranges.
Otherwise gdb will silently skip it. When DW_AT_high_pc is a length instead of an address, the
DWARF version must be at least 4.

IRC log of #gdb on irc.freenode.org at 2020-04-23

/* Detailed source-code truncated for AI context efficiency. */

Compiler Rustc Codegen Cranelift Docs Rustc Testing (`compiler/rustc_codegen_cranelift/docs/rustc_testing.md`) Copy Section

Building and testing with changes in rustc code

This is useful when changing code in rustc_codegen_cranelift as part of changing main Rust repository.
This can happen, for example, when you are implementing a new compiler intrinsic.

Instruction below uses $RustCheckoutDir as substitute for any folder where you cloned Rust repository.

You need to do this steps to successfully compile and use the cranelift backend with your changes in rustc code:

1. cd $RustCheckoutDir
2. Run python x.py setup and choose option for compiler (b).
3. Build compiler and necessary tools: python x.py build --stage=2 compiler library/std src/tools/rustdoc src/tools/rustfmt
   • (Optional) You can also build cargo by adding src/tools/cargo to previous command.
4. Copy cargo from a nightly toolchain: cp $(rustup +nightly which cargo) ./build/host/stage2/bin/cargo. Note that you would need to do this every time you rebuilt rust repository.
5. Link your new rustc to toolchain: rustup toolchain link stage2 ./build/host/stage2/.
6. (Windows only) compile the build system: rustc +stage2 -O build_system/main.rs -o y.exe.
7. You need to prefix every ./y.sh (or y if you built build_system/main.rs as y) command by rustup run stage2 to make cg_clif use your local changes in rustc.

• rustup run stage2 ./y.sh prepare
• rustup run stage2 ./y.sh build
• (Optional) run tests: rustup run stage2 ./y.sh test

8. Now you can use your cg_clif build to compile other Rust programs, e.g. you can open any Rust crate and run commands like $RustCheckoutDir/compiler/rustc_codegen_cranelift/dist/cargo-clif build --release.

You can also set rust-analyzer.rustc.source to your rust workspace to get rust-analyzer to understand your changes.

Compiler Rustc Codegen Cranelift Docs Usage (`compiler/rustc_codegen_cranelift/docs/usage.md`) Copy Section

Usage

rustc_codegen_cranelift can be used as a near-drop-in replacement for cargo build or cargo run for existing projects.

Assuming $cg_clif_dir is the directory you cloned this repo into and you followed the instructions (y.sh prepare and y.sh build or test.sh).

Cargo Copy Chapter

In the directory with your project (where you can do the usual cargo build), run:

$ $cg_clif_dir/dist/cargo-clif build

This will build your project with rustc_codegen_cranelift instead of the usual LLVM backend.

Rustc Copy Chapter

You should prefer using the Cargo method.

$ $cg_clif_dir/dist/rustc-clif my_crate.rs

Jit mode Copy Chapter

⚠⚠⚠ The JIT mode is highly experimental. It may be slower than AOT compilation due to lack of incremental compilation. It may also be hard to setup if you have cargo dependencies. ⚠⚠⚠

In jit mode cg_clif will immediately execute your code without creating an executable file.

This requires all dependencies to be available as dynamic library.
The jit mode will probably need cargo integration to make this possible.

$ $cg_clif_dir/dist/cargo-clif jit

or

$ $cg_clif_dir/dist/rustc-clif -Cllvm-args=jit-mode -Cprefer-dynamic my_crate.rs

Shell Copy Chapter

These are a few functions that allow you to easily run rust code from the shell using cg_clif as jit.

function jit_naked() {
    echo "$@" | $cg_clif_dir/dist/rustc-clif - -Zunstable-options -Cllvm-args=jit-mode -Cprefer-dynamic
}

function jit() {
    jit_naked "fn main() { $@ }"
}

function jit_calc() {
    jit 'println!("0x{:x}", ' $@ ');';
}

Compiler Rustc Codegen Gcc Doc Add Attribute (`compiler/rustc_codegen_gcc/doc/add-attribute.md`) Copy Section

Add support for a new function attribute

To add support for a new function attribute in libgccjit, you need to do the following steps:

1. Copy the corresponding function from c-family/c-attribs.cc into jit/dummy-frontend.cc. For example if you add the target attribute, the function name will be handle_target_attribute.
2. Copy the corresponding entry from the c_common_attribute_table variable in the c-family/c-attribs.cc file into the jit_attribute_table variable in jit/dummy-frontend.cc.
3. Add a new variant in the gcc_jit_fn_attribute enum in the jit/libgccjit.h file.
4. Add a test to ensure the attribute is correctly applied in gcc/testsuite/jit.dg/. Take a look at gcc/testsuite/jit.dg/test-nonnull.c if you want an example.
5. Run the example like this (in your gcc-build folder): make check-jit RUNTESTFLAGS="-v -v -v jit.exp=jit.dg/test-nonnull.c"

Once done, you need to update the gccjit.rs crate to add the new enum variant in the corresponding enum (FnAttribute).

Finally, you need to update this repository by calling the relevant API you added in gccjit.rs.

To test it, build gcc, run cargo update -p gccjit and then you can test the generated output for a given Rust crate.

Compiler Rustc Codegen Gcc Doc Debugging Libgccjit (`compiler/rustc_codegen_gcc/doc/debugging-libgccjit.md`) Copy Section

Debugging libgccjit

Sometimes, libgccjit will crash and output an error like this:

during RTL pass: expand
libgccjit.so: error: in expmed_mode_index, at expmed.h:249
0x7f0da2e61a35 expmed_mode_index
	../../../gcc/gcc/expmed.h:249
0x7f0da2e61aa4 expmed_op_cost_ptr
	../../../gcc/gcc/expmed.h:271
0x7f0da2e620dc sdiv_cost_ptr
	../../../gcc/gcc/expmed.h:540
0x7f0da2e62129 sdiv_cost
	../../../gcc/gcc/expmed.h:558
0x7f0da2e73c12 expand_divmod(int, tree_code, machine_mode, rtx_def*, rtx_def*, rtx_def*, int)
	../../../gcc/gcc/expmed.c:4335
0x7f0da2ea1423 expand_expr_real_2(separate_ops*, rtx_def*, machine_mode, expand_modifier)
	../../../gcc/gcc/expr.c:9240
0x7f0da2cd1a1e expand_gimple_stmt_1
	../../../gcc/gcc/cfgexpand.c:3796
0x7f0da2cd1c30 expand_gimple_stmt
	../../../gcc/gcc/cfgexpand.c:3857
0x7f0da2cd90a9 expand_gimple_basic_block
	../../../gcc/gcc/cfgexpand.c:5898
0x7f0da2cdade8 execute
	../../../gcc/gcc/cfgexpand.c:6582

To see the code which causes this error, call the following function:

gcc_jit_context_dump_to_file(ctxt, "/tmp/output.c", 1 /* update_locations */)

This will create a C-like file and add the locations into the IR pointing to this C file.
Then, rerun the program and it will output the location in the second line:

libgccjit.so: /tmp/something.c:61322:0: error: in expmed_mode_index, at expmed.h:249

Or add a breakpoint to add_error in gdb and print the line number using:

p loc->m_line
p loc->m_filename->m_buffer

To print a debug representation of a tree:

debug_tree(expr);

(defined in print-tree.h)

To print a debug representation of a gimple struct:

debug_gimple_stmt(gimple_struct)

To get the rustc command to run in gdb, add the --verbose flag to cargo build.

To have the correct file paths in gdb instead of /usr/src/debug/gcc/libstdc++-v3/libsupc++/eh_personality.cc:

Maybe by calling the following at the beginning of gdb:

set substitute-path /usr/src/debug/gcc /path/to/gcc-repo/gcc

FIXME(antoyo): but that's not what I remember I was doing.

Compiler Rustc Codegen Gcc Doc Debugging (`compiler/rustc_codegen_gcc/doc/debugging.md`) Copy Section

Debugging

How to debug GCC LTO Copy Chapter

Run the command with -v -save-temps and then extract the lto1 line from the output and run that under the debugger.

How to debug stdarch tests that cannot be run locally Copy Chapter

First, run the tests normally:

cd build/build_sysroot/sysroot_src/library/stdarch/ STDARCH_TEST_EVERYTHING=1 CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUNNER="sde -future -rtm_mode full --" TARGET=x86_64-unknown-linux-gnu ../../../../../y.sh cargo test Copy Chapter

It will show the command it ran, something like this:

process didn't exit successfully: `sde -future -rtm_mode full -- /home/user/projects/rustc_codegen_gcc/build/build_sysroot/sysroot_src/library/stdarch/target/debug/deps/core_arch-fd2d75f89baae5c6` (signal: 11, SIGSEGV: invalid memory reference) Copy Chapter

Then add the -debug flag to it:

sde -debug -future -rtm_mode full -- /home/user/projects/rustc_codegen_gcc/build/build_sysroot/sysroot_src/library/stdarch/target/debug/deps/core_arch-fd2d75f89baae5c6 Copy Chapter

To see the symbols in gdb, specify the executable in your command:

gdb /home/user/projects/rustc_codegen_gcc/build/build_sysroot/sysroot_src/library/stdarch/target/debug/deps/core_arch-fd2d75f89baae5c6 Copy Chapter

and then write the gdb command that sde tells you to use, something like:

target remote :51299 Copy Chapter

Compiler Rustc Codegen Gcc Doc Errors (`compiler/rustc_codegen_gcc/doc/errors.md`) Copy Section

Common errors

This file lists errors that were encountered and how to fix them.

`failed to build archive` error Copy Section

When you get this error:

error: failed to build archive: failed to open object file: No such file or directory (os error 2)

That can be caused by the fact that you try to compile with lto = "fat", but you didn't compile the sysroot with LTO.
(Not sure if that's the reason since I cannot reproduce anymore. Maybe it happened when forgetting setting FAT_LTO.)

ld: cannot find crtbegin.o Copy Section

When compiling an executable with libgccjit, if setting the *LIBRARY_PATH variables to the install directory, you will get the following errors:

ld: cannot find crtbegin.o: No such file or directory
ld: cannot find -lgcc: No such file or directory
ld: cannot find -lgcc: No such file or directory
libgccjit.so: error: error invoking gcc driver

To fix this, set the variables to gcc-build/build/gcc.

Compiler Rustc Codegen Gcc Doc Gimple (`compiler/rustc_codegen_gcc/doc/gimple.md`) Copy Section

GIMPLE

You can see the full documentation about what GIMPLE is here. In this document we will explain how to generate it.

First, we'll copy the content from gcc/gcc/testsuite/jit.dg/test-const-attribute.c into a
file named local.c and remove the content we're not interested in:

- /* { dg-do compile { target x86_64-*-* } } */
...
- /* We don't want set_options() in harness.h to set -O3 to see that the const
-    attribute affects the optimizations. */
- #define TEST_ESCHEWS_SET_OPTIONS
- static void set_options (gcc_jit_context *ctxt, const char *argv0)
- {
-   // Set "-O3".
-   gcc_jit_context_set_int_option(ctxt, GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 3);
- }
-
- #define TEST_COMPILING_TO_FILE
- #define OUTPUT_KIND      GCC_JIT_OUTPUT_KIND_ASSEMBLER
- #define OUTPUT_FILENAME  "output-of-test-const-attribute.c.s"
- #include "harness.h"
...
- /* { dg-final { jit-verify-output-file-was-created "" } } */
- /* Check that the loop was optimized away */
- /* { dg-final { jit-verify-assembler-output-not "jne" } } */

Then we'll add a main function which will call the create_code function but
also add the calls we need to generate the GIMPLE:

int main() {
    gcc_jit_context *ctxt = gcc_jit_context_acquire();
    // To set `-O3`, update it depending on your needs.
    gcc_jit_context_set_int_option(ctxt, GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 3);
    // Very important option to generate the gimple format.
    gcc_jit_context_set_bool_option(ctxt, GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE, 1);
    create_code(ctxt, NULL);

    gcc_jit_context_compile(ctxt);
    // If you want to compile to assembly (or any other format) directly, you can
    // use the following call instead:
    // gcc_jit_context_compile_to_file(ctxt, GCC_JIT_OUTPUT_KIND_ASSEMBLER, "out.s");

    return 0;
}

Then we can compile it by using:

gcc local.c -I `pwd`/gcc/gcc/jit/ -L `pwd`/gcc-build/gcc -lgccjit -o out

And finally when you run it:

LD_LIBRARY_PATH=`pwd`/gcc-build/gcc LIBRARY_PATH=`pwd`/gcc-build/gcc ./out

It should display:

__attribute__((const))
int xxx ()
{
  int D.3394;
  int sum;
  int x;

  <D.3377>:
  x = 45;
  sum = 0;
  goto loop_cond;
  loop_cond:
  x = x >> 1;
  if (x != 0) goto after_loop; else goto loop_body;
  loop_body:
  _1 = foo (x);
  _2 = _1 * 2;
  x = x + _2;
  goto loop_cond;
  after_loop:
  D.3394 = sum;
  return D.3394;
}

An alternative way to generate the GIMPLE is to replace:

gcc_jit_context_set_bool_option(ctxt, GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE, 1);

with:

gcc_jit_context_add_command_line_option(ctxt, "-fdump-tree-gimple");

(although you can have both at the same time too). Then you can compile it like previously. Only one difference: before executing it, I recommend to run:

rm -rf /tmp/libgccjit-*

to make it easier for you to know which folder to look into.

Once the execution is done, you should now have a file with path looking like /tmp/libgccjit-9OFqkD/fake.c.006t.gimple which contains the GIMPLE format.

Compiler Rustc Codegen Gcc Doc Sending Gcc Patch (`compiler/rustc_codegen_gcc/doc/sending-gcc-patch.md`) Copy Section

This guide explains what to do to send a GCC patch for review.

All the commands are supposed to be run in the folder where you cloned GCC.

./contrib/gcc-changelog/git_check_commit.py

You can provide a specific commit hash:

./contrib/gcc-changelog/git_check_commit.py abdef78989

a range:

./contrib/gcc-changelog/git_check_commit.py HEAD~2

or even a comparison with a remote branch:

./contrib/gcc-changelog/git_check_commit.py upstream/master..HEAD

When there is no more errors, generate the git patch:

git format-patch -1 `git rev-parse --short HEAD`

Then you can run the remaining checks using:

contrib/check_GNU_style.sh 0001-your-patch.patch

When you have no more errors, you can send the .patch file to GCC by sending an
email to [email protected] and to the relevant GCC mailing lists
depending on what your patch changes. You can find the list of the mailing lists
here.

You can find more information about "contributing to GCC" here.

Compiler Rustc Codegen Gcc Doc Subtree (`compiler/rustc_codegen_gcc/doc/subtree.md`) Copy Section

git subtree sync

rustc_codegen_gcc is a subtree of the rust compiler. As such, it needs to be
synced from time to time to ensure changes that happened on their side are also
included on our side.

How to install a forked git-subtree Copy Section

Using git-subtree with rustc requires a patched git to make it work.
The PR that is needed is here.
Use the following instructions to install it:

git clone [email protected]:tqc/git.git
cd git
git checkout tqc/subtree
make
make install
cd contrib/subtree
make
cp git-subtree ~/bin

Syncing with rust compiler Copy Section

Do a sync with this command:

PATH="$HOME/bin:$PATH" ~/bin/git-subtree push -P compiler/rustc_codegen_gcc/ ../rustc_codegen_gcc/ sync_branch_name
cd ../rustc_codegen_gcc
git checkout master
git pull
git checkout sync_branch_name
git merge master

To send the changes to the rust repo:

cd ../rust
git pull origin master
git checkout -b subtree-update_cg_gcc_YYYY-MM-DD
PATH="$HOME/bin:$PATH" ~/bin/git-subtree pull --prefix=compiler/rustc_codegen_gcc/ https://github.com/rust-lang/rustc_codegen_gcc.git master
# Don't forget to update the `gcc` submodule to the same version as the
# one in `rustc_codegen_gcc/libgccjit.version`.
git push

# Immediately merge the merge commit into cg_gcc to prevent merge conflicts when syncing from rust-lang/rust later.
PATH="$HOME/bin:$PATH" ~/bin/git-subtree push -P compiler/rustc_codegen_gcc/ ../rustc_codegen_gcc/ sync_branch_name

FIXME: write a script that does the above.

https://rust-lang.zulipchat.com/#narrow/stream/301329-t-devtools/topic/subtree.20madness/near/258877725

Compiler Rustc Codegen Gcc Doc Tests (`compiler/rustc_codegen_gcc/doc/tests.md`) Copy Section

Tests

Show the rustc command for UI tests Copy Chapter

Add --test-args "--verbose" to ./x.py test.

Compiler Rustc Codegen Gcc Doc Tips (`compiler/rustc_codegen_gcc/doc/tips.md`) Copy Section

Tips

The following shows how to do different random small things we encountered and thought could
be useful.

How to send arguments to the GCC linker Copy Section

CG_RUSTFLAGS="-Clink-args=-save-temps -v" ../y.sh cargo build

How to send arguments to GCC Copy Section

The -Cllvm-args rustc flag is repurposed by rustc_codegen_gcc to pass arguments directly to the GCC backend. You can use it via the CG_RUSTFLAGS environment variable. For example, to pass a -f flag to GCC:

CG_RUSTFLAGS="-Cllvm-args=-fflag-name" ../y.sh cargo build

How to see the personality functions in the asm dump Copy Section

CG_RUSTFLAGS="-Clink-arg=-save-temps -v -Clink-arg=-dA" ../y.sh cargo build

How to see the LLVM IR for a sysroot crate Copy Section

cargo build -v --target x86_64-unknown-linux-gnu -Zbuild-std
# Take the command from the output and add --emit=llvm-ir

To prevent the linker from unmangling symbols Copy Section

Run with:

COLLECT_NO_DEMANGLE=1

How to use a custom-build rustc Copy Section

• Build the stage2 compiler (rustup toolchain link debug-current build/x86_64-unknown-linux-gnu/stage2).
• Clean and rebuild the codegen with debug-current in the file rust-toolchain.toml.

How to use a custom sysroot source path Copy Section

If you wish to build a custom sysroot, pass the path of your sysroot source to --sysroot-source during the prepare step, like so:

./y.sh prepare --sysroot-source /path/to/custom/source

How to use [mem-trace](https://github.com/antoyo/mem-trace) Copy Section

rustc needs to be built without jemalloc so that mem-trace can overload malloc since jemalloc is linked statically, so a LD_PRELOAD-ed library won't have a chance to intercept the calls to malloc.

How to generate GIMPLE Copy Section

If you need to check what gccjit is generating (GIMPLE), then take a look at how to
generate it in gimple.md.

How to build a cross-compiling libgccjit Copy Section

Building libgccjit

• Follow the instructions on this repo.

Configuring rustc_codegen_gcc

• Run ./y.sh prepare --cross so that the sysroot is patched for the cross-compiling case.
• Set the path to the cross-compiling libgccjit in gcc-path (in config.toml).
• Make sure you have the linker for your target (for instance m68k-unknown-linux-gnu-gcc) in your $PATH. You can specify which linker to use via CG_RUSTFLAGS="-Clinker=<linker>", for instance: CG_RUSTFLAGS="-Clinker=m68k-unknown-linux-gnu-gcc". Specify the target when building the sysroot: ./y.sh build --sysroot --target-triple m68k-unknown-linux-gnu.
• Build your project by specifying the target and the linker to use: CG_RUSTFLAGS="-Clinker=m68k-unknown-linux-gnu-gcc" ../y.sh cargo build --target m68k-unknown-linux-gnu.

If the target is not yet supported by the Rust compiler, create a target specification file (note that the arch specified in this file must be supported by the rust compiler).
Then, you can use it the following way:

• Add the target specification file using --target as an absolute path to build the sysroot: ./y.sh build --sysroot --target-triple m68k-unknown-linux-gnu --target $(pwd)/m68k-unknown-linux-gnu.json
• Build your project by specifying the target specification file: ../y.sh cargo build --target path/to/m68k-unknown-linux-gnu.json.

If you get the following error:

/usr/bin/ld: unrecognised emulation mode: m68kelf

Make sure you set gcc-path (in config.toml) to the install directory.

Src Doc Rustc Dev Guide CODE OF CONDUCT (`src/doc/rustc-dev-guide/CODE_OF_CONDUCT.md`) Copy Section

The Rust Code of Conduct

This repository follows the Code of Conduct of the Rust organization.

Src Doc Rustc Dev Guide Src SUMMARY (`src/doc/rustc-dev-guide/src/SUMMARY.md`) Copy Section

Summary

Getting Started

About this guide

Building and debugging `rustc`

• How to build and run the compiler
  • Quickstart
  • Prerequisites
  • Suggested workflows
  • Distribution artifacts
  • Building documentation
  • Rustdoc overview
  • Adding a new target
  • Optimized build
• Testing the compiler
  • Running tests
    • Testing with Docker
    • Testing with CI
  • Adding new tests
  • Best practices
  • Compiletest
    • UI tests
    • Test directives
    • Minicore
  • Ecosystem testing
    • Crater
    • Fuchsia
    • Rust for Linux
  • Codegen backend testing
    • Cranelift codegen backend (stub)
    • GCC codegen backend
  • Performance testing
  • Autodiff CI job
  • Pre-stabilization CI job for the next solver and polonius alpha
  • Parallel frontend CI job
  • Standard library semver breakage test
  • Misc info
• Debugging the compiler
  • Using the tracing/logging instrumentation
• Profiling the compiler
  • with the linux perf tool
  • with Windows Performance Analyzer
  • with the Rust benchmark suite
• crates.io dependencies

Contributing to Rust

• Contribution procedures
• PR lifecycle
• Writing rustc-dev-guide documentation
• About the compiler team
• Using Git
• Mastering @rustbot
• Running LLMs
  • Writing code with LLMs
  • Reviewing code with LLMs
• Walkthrough: adding a new test
• Implementing new language features
• Stability guarantees
• Stability attributes
• Stabilizing language features
  • Stabilization report template
• Feature Gates
• Walkthrough: a new language feature, from design to stabilization
• Coding conventions
• Procedures for breaking changes
• Using external repositories
• Fuzzing
• Notification groups
  • Apple
  • ARM
  • Emscripten
  • Fuchsia
  • LoongArch
  • RISC-V
  • Rust for Linux
  • WASI
  • WebAssembly
  • Windows
  • GPU target
• Licenses
• Editions

Bootstrapping

• Prologue
• What Bootstrapping does
• How Bootstrap does it
• Writing tools in Bootstrap
• Debugging bootstrap
• cfg(bootstrap) in dependencies

High-level compiler architecture

• Prologue
• Overview of the compiler
• The compiler source code
• Queries: demand-driven compilation
  • The Query Evaluation Model in detail
  • Incremental compilation
  • Incremental compilation in detail
  • Debugging and testing
  • Salsa
• Memory management in rustc
• Serialization in rustc
• Parallel compilation
• Rustdoc internals
  • Search
  • The rustdoc-html test suite
  • The rustdoc-gui test suite (stub)
  • The rustdoc-json test suite
• GPU offload internals
  • Installation
  • Usage
  • Contributing
• Autodiff internals
  • Installation
  • How to debug
  • Autodiff flags
  • Type Trees

Source code representation

• Prologue
• Syntax and the AST
  • Lexing and parsing
  • Macro expansion
  • Name resolution
  • Attributes
  • #[test] implementation
  • Panic implementation
  • AST validation
  • Feature gate checking
  • Lang Items
• The HIR (High-level IR)
  • Lowering AST to HIR
  • Attribute Parsing
  • Debugging
• Ambig/Unambig Types and Consts
• The THIR (Typed High-level IR)
• The MIR (Mid-level IR)
  • MIR construction
  • MIR visitor and traversal
  • MIR queries and passes: getting the MIR
• Inline assembly

Supporting infrastructure

• Command-line arguments
• rustc_driver and rustc_interface
  • External rustc_drivers
  • Example: Type checking
  • Example: Getting diagnostics
• Errors and lints
  • Diagnostic and subdiagnostic structs
  • Translation
  • LintStore
  • Error codes
  • Diagnostic items
  • ErrorGuaranteed

Analysis

• Prologue
• Generic parameter definitions
  • EarlyBinder and instantiating parameters
• Binders and Higher ranked regions
  • Instantiating binders
• Early vs Late bound parameters
• The ty module: representing types
  • ADTs and Generic Arguments
  • Parameter types/consts/regions
• TypeFolder and TypeFoldable
• Aliases and normalization
• Typing/Param envs
• Type inference
• Trait solving
  • Higher-ranked trait bounds
  • Caching subtleties
  • Implied bounds
  • Specialization
  • Chalk-based trait solving
    • Lowering to logic
    • Goals and clauses
    • Canonical queries
    • Canonicalization
  • Next-gen trait solving
    • Invariants of the type system
    • The solver
    • Candidate preference
    • Canonicalization
    • Coinduction
    • Caching
    • Proof trees
    • Opaque types
    • Significant changes and quirks
    • Sharing the trait solver with rust-analyzer
  • Unsize and CoerceUnsized traits
  • Having separate Trait and Projection bounds
• Well-formedness
• Variance
• Coherence checking
• HIR Type checking
  • Coercions
  • Method lookup
• Const generics
• Opaque types
  • Inference details
  • Return Position Impl Trait In Trait
  • Region inference restrictions
• Const traits and const condition checking
• Pattern and exhaustiveness checking
• Unsafety checking
• MIR dataflow
• Drop elaboration
• The borrow checker
  • Tracking moves and initialization
    • Move paths
  • MIR type checker
  • Drop check
  • Region inference
    • Constraint propagation
    • Lifetime parameters
    • Member constraints
    • Placeholders and universes
    • Closure constraints
    • Error reporting (stub)
  • Two-phase-borrows
  • Debugging the borrow checker
• Closure capture inference
• Async closures/"coroutine-closures"

MIR to binaries

• Prologue
• MIR optimizations
• Debugging MIR
• Constant evaluation
  • Interpreter
• Monomorphization
• Lowering MIR
• Code generation
  • Updating LLVM
  • Debugging LLVM
  • Backend Agnostic Codegen
  • Implicit caller location
• Debug info
  • Rust codegen
  • LLVM codegen
  • Debugger internals
    • LLDB internals
    • GDB internals (stub)
  • Debugger visualizers
    • LLDB - Python Providers
    • GDB - Python Providers
    • CDB - Natvis (stub)
  • Testing (stub)
  • (Lecture notes) Debugging support in the Rust compiler
• Libraries and metadata
• Profile-guided optimization
• LLVM source-based code coverage
• Sanitizers support

Appendix A: Background topics

Appendix B: Glossary

Appendix C: Code Index

Appendix D: Compiler Lecture Series

Appendix E: Bibliography

Appendix F: Reading club sessions

Appendix Z: HumorRust

Src Doc Rustc Dev Guide Src About This Guide (`src/doc/rustc-dev-guide/src/about-this-guide.md`) Copy Section

About this guide

This guide is meant to help document how rustc – the Rust compiler – works,
as well as to help new contributors get involved in rustc development.

Note that this guide is intended as a reference; it's recommended that you search
for the docs you're looking for instead of reading them top to bottom.

There are several parts to this guide:

1. Building and debugging rustc:
   Contains information that should be useful no matter how you are contributing,
   about building, debugging, profiling, etc.
2. Contributing to Rust:
   Contains information that should be useful no matter how you are contributing,
   about procedures for contribution, using git and GitHub, stabilizing features, etc.
3. Bootstrapping:
   Describes how the Rust compiler builds itself using previous versions, including
   an introduction to the bootstrap process and debugging methods.
4. High-level compiler architecture:
   Discusses the high-level architecture of the compiler and stages of the compile process.
5. Source code representation:
   Describes the process of taking raw source code from the user
   and transforming it into various forms that the compiler can work with easily.
6. Supporting infrastructure:
   Covers command-line argument conventions, compiler entry points like rustc_driver and
   rustc_interface, and the design and implementation of errors and lints.
7. Analysis:
   Discusses the analyses that the compiler uses to check various properties of the code
   and inform later stages of the compile process (e.g., type checking).
8. Mir to binaries: How linked executable machine code is generated.
9. Appendices at the end with useful reference information.
   There are a few of these with different information, including a glossary.

Constant change Copy Section

Keep in mind that rustc is a real production-quality product,
being worked upon continuously by a sizeable set of contributors.
As such, it has its fair share of codebase churn and technical debt.
In addition, many of the ideas discussed throughout this guide are idealized designs
that are not fully realized yet.
All this makes keeping this guide completely up to date on everything very hard!

The guide itself is of course open source as well,
and the sources are hosted on a GitHub repository.
If you find any mistakes in the guide, please file an issue.
Even better, open a PR with a correction!

If you do contribute to the guide,
please see the corresponding subsection on writing documentation in this guide.

“‘All conditioned things are impermanent’ —
when one sees this with wisdom, one turns away from suffering.”
The Dhammapada, verse 277

Other places to find information Copy Chapter

This guide, the one you are currently reading,
contains information about how various parts of the compiler work,
and how to contribute to the compiler.

You might also find the following sites useful:

• rustc API docs -- rustdoc documentation for the compiler, devtools, and internal tools
• Forge -- contains documentation about Rust infrastructure, team procedures, and more
• rust-lang/rust's LLM policy
• compiler-team -- the home-base for the Rust compiler team, with description
  of the team procedures, active working groups, and the team calendar.
• std-dev-guide -- a similar guide for developing the standard library.
• rust-analyzer book -- documentation for the rust-analyzer.
• The t-compiler Zulip
• The Rust Internals forum, a place to ask questions and discuss Rust's internals
• The Rust reference, even though it doesn't specifically talk about
  Rust's internals, is a great resource nonetheless
• Although out of date, Tom Lee's great blog article is very helpful
• The Rust Compiler Testing Docs
• For @bors, this cheat sheet is helpful
• Google is always helpful when programming.
  You can search all Rust documentation (the standard library,
  the compiler, the books, the references, and the guides) to quickly find
  information about the language and compiler.
• You can also use Rustdoc's built-in search feature to find documentation on
  types and functions within the crates you're looking at.
  You can also search by type signature!
  For example, searching for * -> vec should find all functions that return a Vec<T>.
  Hint: Find more tips and keyboard shortcuts by typing ? on any Rustdoc page!

Src Doc Rustc Dev Guide Src Ambig Unambig Ty And Consts (`src/doc/rustc-dev-guide/src/ambig-unambig-ty-and-consts.md`) Copy Section

Ambig/Unambig Types and Consts

Types and Consts args in the AST/HIR can be in two kinds of positions ambiguous (ambig) or unambiguous (unambig).
Ambig positions are where it would be valid to parse either a type or a const.
Unambig positions are where only one kind would be valid to parse.

fn func<T, const N: usize>(arg: T) {
    //                          ^ Unambig type position
    let a: _ = arg;
    //     ^ Unambig type position

    func::<T, N>(arg);
    //     ^  ^
    //     ^^^^ Ambig position

    let _: [u8; 10];
    //      ^^  ^^ Unambig const position
    //      ^^ Unambig type position
}

Most types/consts in ambig positions are able to be disambiguated as either a type or const during parsing.
The only exceptions to this are paths and inferred generic arguments.

Paths Copy Chapter

struct Foo<const N: usize>;

fn foo<const N: usize>(_: Foo<N>) {}

At parse time we parse all unbraced generic arguments as types (ie they wind up as ast::GenericArg::Ty).
In the above example this means we would parse the generic argument to Foo as an ast::GenericArg::Ty wrapping a ast::Ty::Path(N).

Then during name resolution:

• When encountering a single segment path with no generic arguments in generic argument position, we will first try to resolve it in the type namespace and if that fails we then attempt to resolve in the value namespace.
• All other kinds of paths we only try to resolve in the type namespace

See LateResolutionVisitor::visit_generic_arg for where this is implemented.

Finally during AST lowering when we attempt to lower a type argument, we first check if it is a Ty::Path and if it resolved to something in the value namespace.
If it did, then we create an anon const and lower to a const argument instead of a type argument.

See LoweringContext::lower_generic_arg for where this is implemented.

Note that the ambiguity for paths is not propgated into the HIR; there's no hir::GenericArg::Path which is turned into either a Ty or Const during HIR ty lowering (though we could do such a thing).

Inferred arguments (`_`) Copy Chapter

struct Foo<const N: usize>;

fn foo() {
    let _unused: Foo<_>;
}

The only generic arguments which remain ambiguous after lowering are inferred generic arguments (_) in path segments.
In the above example,
it is not clear at parse time whether the _ argument to Foo is an inferred type argument,
or an inferred const argument.

In ambig AST positions, inferred arguments are parsed as an ast::GenericArg::Ty wrapping a ast::Ty::Infer.
Then, during AST lowering, when lowering an ast::GenericArg::Ty,
we check if it is an inferred type, and if so, lower to a hir::GenericArg::Infer.

In unambig AST positions, inferred arguments are parsed as either ast::Ty::Infer or ast::AnonConst.
The AnonConst case is quite strange;
we use ast::ExprKind::Underscore to represent the "body" of the "anon const",
although in reality we do not actually lower this to an anon const in the HIR.

It may be worth seeing if we can refactor the AST to have ast::GenericArg::Infer and then get rid of this overloaded meaning of AnonConst,
as well as the reuse of ast::Ty::Infer in ambig positions.

In unambig AST positions, during AST lowering we lower inferred arguments to hir::TyKind::Infer or hir::ConstArgKind::Infer depending on whether it is a type or const position respectively.
In ambig AST positions, during AST lowering we lower inferred arguments to hir::GenericArg::Infer.
See LoweringContext::lower_generic_arg for where this is implemented.

A naive implementation of this would result in there being potentially 5 places where you might think an inferred type/const could be found in the HIR from looking at the structure of the HIR:

1. In unambig type position as a TyKind::Infer
2. In unambig const arg position as a ConstArgKind::Infer
3. In an ambig position as a GenericArg::Type(TyKind::Infer)
4. In an ambig position as a GenericArg::Const(ConstArgKind::Infer)
5. In an ambig position as a GenericArg::Infer

Note that places 3 and 4 would never actually be possible to encounter as we always lower to GenericArg::Infer in generic arg position.

This has a few failure modes:

• People may write visitors which check for GenericArg::Infer but forget to check for hir::TyKind/ConstArgKind::Infer, only handling infers in ambig positions by accident.
• People may write visitors which check for TyKind/ConstArgKind::Infer but forget to check for GenericArg::Infer, only handling infers in unambig positions by accident.
• People may write visitors which check for GenericArg::Type/Const(TyKind/ConstArgKind::Infer) and GenericArg::Infer, not realising that we never represent inferred types/consts in ambig positions as a GenericArg::Type/Const.
• People may write visitors which check for only TyKind::Infer and not ConstArgKind::Infer forgetting that there are also inferred const arguments (and vice versa).

To make writing HIR visitors less error prone when caring about inferred types/consts we have a relatively complex system:

1. We have different types in the compiler for when a type or const is in an unambig or ambig position, Ty<AmbigArg> and Ty<()>.
   AmbigArg is an uninhabited type which we use in the Infer variant of TyKind and ConstArgKind to selectively "disable" it if we are in an ambig position.

2. The visit_ty and visit_const_arg methods on HIR visitors only accept the ambig position versions of types/consts.
   Unambig types/consts are implicitly converted to ambig types/consts during the visiting process, with the Infer variant handled by a dedicated visit_infer method.

This has a number of benefits:

• It's clear that GenericArg::Type/Const cannot represent inferred type/const arguments
• Implementors of visit_ty and visit_const_arg will never encounter inferred types/consts making it impossible to write a visitor that seems to work right but handles edge cases wrong
• The visit_infer method handles all cases of inferred type/consts in the HIR making it easy for visitors to handle inferred type/consts in one dedicated place and not forget cases

Src Doc Rustc Dev Guide Src Asm (`src/doc/rustc-dev-guide/src/asm.md`) Copy Section

Inline assembly

Overview Copy Chapter

Inline assembly in rustc mostly revolves around taking an asm! macro invocation and plumbing it
through all of the compiler layers down to LLVM codegen.
Throughout the various stages,
an InlineAsm generally consists of 3 components:

• The template string, which is stored as an array of InlineAsmTemplatePiece.
  Each piece represents either a literal or a placeholder for an operand
  (just like format strings).

  rust Copy

  pub enum InlineAsmTemplatePiece {
      String(String),
      Placeholder { operand_idx: usize, modifier: Option<char>, span: Span },
  }

• The list of operands to the asm! (in, [late]out, in[late]out, sym, const).
  These are represented differently at each stage of lowering,
  but follow a common pattern:

  • in, out, and inout all have an associated register class (reg)
    or explicit register ("eax").
  • inout has 2 forms:
    one with a single expression that is both read from and written to,
    and one with two separate expressions for the input and output parts.
  • out and inout have a late flag (lateout / inlateout) to indicate that the register
    allocator is allowed to reuse an input register for this output.
  • out and the split variant of inout allow _ to be specified for an output,
    which means that the output is discarded.
    This is used to allocate scratch registers for assembly code.
  • const refers to an anonymous constants,
    and generally works like an inline const.
  • sym is a bit special since it only accepts a path expression,
    which must point to a static or a fn.

• The options set at the end of the asm! macro.
  The only ones that are of particular interest to
  rustc are NORETURN which makes asm! return ! instead of (),
  and RAW which disables format string parsing.
  The remaining options are mostly passed through to LLVM with little processing.

  rust Copy

  bitflags::bitflags! {
      pub struct InlineAsmOptions: u16 {
          const PURE = 1 << 0;
          const NOMEM = 1 << 1;
          const READONLY = 1 << 2;
          const PRESERVES_FLAGS = 1 << 3;
          const NORETURN = 1 << 4;
          const NOSTACK = 1 << 5;
          const ATT_SYNTAX = 1 << 6;
          const RAW = 1 << 7;
          const MAY_UNWIND = 1 << 8;
      }
  }

AST Copy Chapter

InlineAsm is represented as an expression in the AST with the ast::InlineAsm type.

The asm! macro is implemented in rustc_builtin_macros and outputs an InlineAsm AST node.
The template string is parsed using fmt_macros,
positional and named operands are resolved to explicit operand indices.
Since target information is not available to macro invocations,
validation of the registers and register classes is deferred to AST lowering.

HIR Copy Chapter

InlineAsm is represented as an expression in the HIR with the hir::InlineAsm type.

AST lowering is where InlineAsmRegOrRegClass is converted from Symbols to an actual register or
register class.
If any modifiers are specified for a template string placeholder, these are
validated against the set allowed for that operand type.
Finally, explicit registers for inputs and
outputs are checked for conflicts (same register used for different operands).

Type checking Copy Chapter

Each register class has an allowlist of types that it may be used with.
After the types of all operands have been determined,
the intrinsicck pass will check that these types are in the allowlist.
It also checks that split inout operands have compatible types and that const
operands are integers or floats.
Suggestions are emitted where needed if a template modifier should
be used for an operand based on the type that was passed into it.

THIR Copy Chapter

InlineAsm is represented as an expression in the THIR with the InlineAsmExpr type.

The only significant change compared to HIR is that Sym has been lowered to either a SymFn
whose expr is a Literal ZST of the fn,
or a SymStatic which points to the DefId of a static.

MIR Copy Chapter

InlineAsm is represented as a Terminator in the MIR with the TerminatorKind::InlineAsm variant

As part of THIR lowering, InOut and SplitInOut operands are lowered to a split form with a
separate in_value and out_place.

Semantically, the InlineAsm terminator is similar to the Call terminator except that it has
multiple output places where a Call only has a single return place output.

Codegen Copy Chapter

Operands are lowered one more time before being passed to LLVM codegen.
This is represented by the InlineAsmOperandRef type from rustc_codegen_ssa.

The operands are lowered to LLVM operands and constraint codes as follows:

• out and the output part of inout operands are added first, as required by LLVM.
  Late output operands have a = prefix added to their constraint code,
  and non-late output operands have a =& prefix added to their constraint code.
• in operands are added normally.
• inout operands are tied to the matching output operand.
• sym operands are passed as function pointers or pointers,
  using the "s" constraint.
• const operands are formatted to a string and directly inserted in the template string.

The template string is converted to LLVM form:

• $ characters are escaped as $$.
• const operands are converted to strings and inserted directly.
• Placeholders are formatted as ${X:M},
  where X is the operand index and M is the modifier character.
  Modifiers are converted from the Rust form to the LLVM form.

The various options are converted to clobber constraints or LLVM attributes;
refer to the RFC for more details.

Note that LLVM is sometimes rather picky about what types it accepts for certain constraint codes
so we sometimes need to insert conversions to/from a supported type.
See the target-specific ISelLowering.cpp files in LLVM
for details of what types are supported for each register class.

Adding support for new architectures Copy Chapter

Adding inline assembly support to an architecture is mostly a matter of defining the registers and
register classes for that architecture.
All the definitions for register classes are located in
compiler/rustc_target/asm/.

Additionally you will need to implement lowering of these register classes to LLVM constraint codes
in compiler/rustc_codegen_llvm/asm.rs.

When adding a new architecture, make sure to cross-reference with the LLVM source code:

• LLVM has restrictions on which types can be used with a particular constraint code.
  Refer to the getRegForInlineAsmConstraint function
  in lib/Target/${ARCH}/${ARCH}ISelLowering.cpp.
• LLVM reserves certain registers for its internal use,
  which causes them to not be saved/restored properly around inline assembly blocks.
  These registers are listed in the getReservedRegs
  function in lib/Target/${ARCH}/${ARCH}RegisterInfo.cpp.
  Any "conditionally" reserved register,
  such as the frame/base pointer,
  must always be treated as reserved for Rust purposes because we
  can't know ahead of time whether a function will require a frame/base pointer.

Tests Copy Chapter

Various tests for inline assembly are available:

• tests/assembly-llvm/asm
• tests/ui/asm
• tests/codegen-llvm/asm-*

Every architecture supported by inline assembly must have exhaustive tests in
tests/assembly-llvm/asm which test all combinations of register classes and types.

Src Doc Rustc Dev Guide Src Ast Validation (`src/doc/rustc-dev-guide/src/ast-validation.md`) Copy Section

AST validation

AST validation is a separate AST pass that visits each
item in the tree and performs simple checks.
This pass doesn't perform any complex analysis, type checking or
name resolution.

Before performing any validation, the compiler first expands the macros.
Then this pass performs validations to check that each AST item is in the correct state.
And when this pass is done, the compiler runs the crate resolution pass.

Validations Copy Chapter

Validations are defined in AstValidator type, which
itself is located in rustc_ast_passes crate.
This type implements various simple checks which emit errors
when certain language rules are broken.

In addition, AstValidator implements Visitor trait
that defines how to visit AST items (which can be functions,
traits, enums, etc).

For each item, visitor performs specific checks.
For example, when visiting a function declaration,
AstValidator checks that the function has:

• no more than u16::MAX parameters;
• c-variadic argument goes the last in the declaration;
• documentation comments aren't applied to function parameters;
• and other validations.

Src Doc Rustc Dev Guide Src Attributes (`src/doc/rustc-dev-guide/src/attributes.md`) Copy Section

Attributes

Attributes come in two types: inert (or built-in) and active (non-builtin).

Builtin/inert attributes Copy Chapter

These attributes are defined in the compiler itself, in
compiler/rustc_feature/src/builtin_attrs.rs and in the attribute parsers.

Examples include #[allow] and #[macro_use].

These attributes have several important characteristics:

• They are always in scope, and do not participate in typical path-based resolution.
• They cannot be renamed.
  For example, use allow as foo will compile, but writing #[foo] will produce an error.
• They are 'inert', meaning they are left as-is by the macro expansion code.
  As a result, any behavior comes as a result of the compiler explicitly checking for their presence.
  For example, lint-related code explicitly checks for #[allow], #[warn], #[deny], and
  #[forbid], rather than the behavior coming from the expansion of the attributes themselves.

For more information on these attributes, see the chapter about attribute parsing.

Note on adding new builtin attributes Copy Section

Warning: Name resolution ambiguity potential when adding new builtin attributes

Please note that adding new builtin attributes (whose name is not reserved, i.e. a new builtin
attribute whose name does not start with rustc), even if unstable-gated, can introduce breakage
from name resolution ambiguity in stable code if (1) the stable code has a macro of the same name
which gets re-exported, or (2) or a proc-macro derive helper attribute of the same name.

Typically, the builtin attributes probably has to start out as #[rustc_foo] instead of #[foo] to
avoid colliding with user-defined macros and proc-macro helper attributes.
Then, prior to stabilization,
a rename to #[foo] should be done separately with a crater run to assess fallout,
with a deliberate breakage FCP proposal for T-lang to consider.

Remember also that crater is not exhaustive and does not contain all existing stable code.

See:

• Built-in attributes are treated differently vs prelude attributes, unstable built-in attributes
  can name-collide with stable macro, and built-in attributes can break back-compat
  #134963 and backlinks within this issue,
  including design discussions on how to fix this kind of breakage hazard.
• Broken build after updating: coverage is ambiguous; ambiguous because of a name conflict with a
  builtin attribute #121157.
• Regression: align is ambiguous #143834.

'Non-builtin'/'active' attributes Copy Chapter

These attributes are defined by a crate - either the standard library, or a proc-macro crate.

Important: Many non-builtin attributes, such as #[derive], are still considered part of the
core Rust language.
However, they are not called 'builtin attributes', since they have a
corresponding definition in the standard library.

Definitions of non-builtin attributes take two forms:

1. Proc-macro attributes, defined via a function annotated with #[proc_macro_attribute] in a
   proc-macro crate.
2. AST-based attributes, defined in the standard library.
   These attributes have special 'stub'
   macros defined in places like library/core/src/macros/mod.rs.

These definitions exist to allow the macros to participate in typical path-based resolution - they
can be imported, re-exported, and renamed just like any other item definition.
However, the body of the definition is empty.
Instead, the macro is annotated with the #[rustc_builtin_macro]
attribute, which tells the compiler to run a corresponding function in rustc_builtin_macros.

All non-builtin attributes have the following characteristics:

• Like all other definitions (e.g. structs), they must be brought into scope via an import.
  Many standard library attributes are included in the prelude - this is why writing #[derive]
  works without an import.
• They participate in macro expansion.
  The implementation of the macro may leave the attribute
  target unchanged, modify the target, produce new AST nodes, or remove the target entirely.

Src Doc Rustc Dev Guide Src Borrow Check (`src/doc/rustc-dev-guide/src/borrow-check.md`) Copy Section

MIR borrow check

The borrow check is Rust's "secret sauce" – it is tasked with enforcing a number of properties:

• That all variables are initialized before they are used.
• That you can't move the same value twice.
• That you can't move a value while it is borrowed.
• That you can't access a place while it is mutably borrowed (except through the reference).
• That you can't mutate a place while it is immutably borrowed.
• etc

The borrow checker operates on the MIR.
An older implementation operated on the HIR.
Doing borrow checking on MIR has several advantages:

• The MIR is far less complex than the HIR; the radical desugaring
  helps prevent bugs in the borrow checker.
  (If you're curious, you can see
  a list of bugs that the MIR-based borrow checker fixes here.)
• Even more importantly, using the MIR enables "non-lexical lifetimes",
  which are regions derived from the control-flow graph.

Major phases of the borrow checker Copy Chapter

The borrow checker source is found in the rustc_borrowck crate.
The main entry point is the mir_borrowck query.

• We first create a local copy of the MIR.
  In the coming steps,
  we will modify this copy in place to modify the types and things to
  include references to the new regions that we are computing.
• We then invoke replace_regions_in_mir to modify our local MIR.
  Among other things, this function will replace all of the regions
  in the MIR with fresh inference variables.
• Next, we perform a number of dataflow analyses that
  compute what data is moved and when.
• We then do a second type check across the MIR:
  the purpose of this type check is to determine all of the constraints between different regions.
• Next, we do region inference, which computes
  the values of each region — basically, the points in the control-flow graph where
  each lifetime must be valid according to the constraints we collected.
• At this point, we can compute the "borrows in scope" at each point.
• Finally, we do a second walk over the MIR, looking at the actions it does and reporting errors.
  For example, if we see a statement like *a + 1,
  we would check that the variable a is initialized and that it is not mutably borrowed,
  as either of those would require an error to be reported.
  Doing this check requires the results of all the previous analyses.

Debugging the borrow checker Copy Chapter

See Debugging the borrow checker and MIR Debugging.

Src Doc Rustc Dev Guide Src Bug Fix Procedure (`src/doc/rustc-dev-guide/src/bug-fix-procedure.md`) Copy Section

Procedures for breaking changes

This page defines the best practices procedure for making bug fixes or soundness
corrections in the compiler that can cause existing code to stop compiling.
This text is based on RFC 1589.

Motivation

From time to time, we encounter the need to make a bug fix, soundness
correction, or other change in the compiler which will cause existing code to stop compiling.
When this happens, it is important that we handle the change in
a way that gives users of Rust a smooth transition.
What we want to avoid is that existing programs suddenly stop compiling with opaque error messages:
we would prefer to have a gradual period of warnings, with clear guidance as to
what the problem is, how to fix it, and why the change was made.
This RFC describes the procedure that we have been developing for handling breaking
changes that aims to achieve that kind of smooth transition.

One of the key points of this policy is that (a) warnings should be issued
initially rather than hard errors if at all possible and (b) every change that
causes existing code to stop compiling will have an associated tracking issue.
This issue provides a point to collect feedback on the results of that change.
Sometimes changes have unexpectedly large consequences or there may be a way to
avoid the change that was not considered.
In those cases,
we may decide to change course and roll back the change,
or find another solution (and if warnings are being used, this is particularly easy to do).

What qualifies as a bug fix? Copy Section

Note that this RFC does not try to define when a breaking change is permitted.
That is already covered under RFC 1122.
This document assumes that the change being made is in accordance with those policies.
Here is a summary of the conditions from RFC 1122:

• Soundness changes: Fixes to holes uncovered in the type system.
• Compiler bugs: Places where the compiler is not implementing the specified
  semantics found in an RFC or lang-team decision.
• Underspecified language semantics: Clarifications to grey areas where the
  compiler behaves inconsistently and no formal behavior had been previously decided.

Please see the RFC for full details!

Detailed design

The procedure for making a breaking change is as follows (each of these steps is
described in more detail below):

1. Do a crater run to assess the impact of the change.
2. Make a special tracking issue dedicated to the change.
3. Do not report an error right away.
   Instead, issue forwards-compatibility lint warnings.
   • Sometimes this is not straightforward.
     See the text below for suggestions on different techniques we have employed in the past.
   • For cases where warnings are infeasible:
     • Report errors, but make every effort to give a targeted error message
       that directs users to the tracking issue
     • Submit PRs to all known affected crates that fix the issue
       • or, at minimum, alert the owners of those crates to the problem and
         direct them to the tracking issue
4. Once the change has been in the wild for at least one cycle, we can
   stabilize the change, converting those warnings into errors.

Finally, for changes to rustc_ast that will affect plugins, the general policy
is to batch these changes.
That is discussed below in more detail.

Tracking issue Copy Section

Every breaking change should be accompanied by a dedicated tracking issue for that change.
The main text of this issue should describe the change being
made, with a focus on what users must do to fix their code.
The issue should be approachable and practical; it may make sense to direct users to an RFC or some
other issue for the full details.
The issue also serves as a place where users can comment with questions or other concerns.

A template for these breaking-change tracking issues can be found here.
An example of how such an issue should look can be found here.

Issuing future compatibility warnings Copy Section

The best way to handle a breaking change is to begin by issuing future-compatibility warnings.
These are a special category of lint warning.
Adding a new future-compatibility warning can be done as follows.

// 1. Define the lint in `compiler/rustc_lint/src/builtin.rs` and
//    add the metadata for the future incompatibility:
declare_lint! {
    pub YOUR_LINT_HERE,
    Warn,
    "illegal use of foo bar baz"
    @future_incompatible = FutureIncompatibleInfo {
        reason: fcw!(FutureReleaseError #1234) // your tracking issue here!
    },
}

// 2. Add a dedicated lint pass for it.
//    This step can be skipped if you emit the lint as part of an existing pass.

#[derive(Default)]
pub struct MyLintPass {
    ...
}

impl {Early,Late}LintPass for MyLintPass {
    ...
}

impl_lint_pass!(MyLintPass => [YOUR_LINT_HERE]);

// 3. emit the lint somewhere in your lint pass:
cx.emit_span_lint(
    YOUR_LINT_HERE,
    pat.span,
    // some diagnostic struct
    MyDiagnostic {
        ...
    },
);

Finally, register the lint in compiler/rustc_lint/src/lib.rs.
There are many examples in that file that already show how to do so.

Helpful techniques

It can often be challenging to filter out new warnings from older, pre-existing errors.
One technique that has been used in the past is to run the older code
unchanged and collect the errors it would have reported.
You can then issue warnings for any errors you would give which do not appear in that original set.
Another option is to abort compilation after the original code completes if
errors are reported: then you know that your new code will only execute when
there were no errors before.

Crater and crates.io

Crater is a bot that will compile all crates.io crates and many
public github repos with the compiler with your changes.
A report will then be generated with crates that ceased to compile with,
or began to compile with your changes.
Crater runs can take a few days to complete.