rustc-dev-guide/src/how-to-build-and-run.md

How to build the compiler and run what you built

The compiler is built using a tool called x.py. You will need to have Python installed to run it. But before we get to that, if you're going to be hacking on rustc, you'll want to tweak the configuration of the compiler. The default configuration is oriented towards running the compiler as a user, not a developer.

Create a config.toml

To start, copy config.toml.example to config.toml:

> cd $RUST_CHECKOUT
> cp config.toml.example config.toml

Then you will want to open up the file and change the following settings (and possibly others, such as llvm.ccache):

[llvm]
# Enables LLVM assertions, which will check that the LLVM bitcode generated
# by the compiler is internally consistent. These are particularly helpful
# if you edit `trans`.
assertions = true

[rust]
# This enables some assertions, but more importantly it enables the `debug!` logging
# macros that are essential for debugging rustc.
debug-assertions = true

# This will make your build more parallel; it costs a bit of runtime
# performance perhaps (less inlining) but it's worth it.
codegen-units = 0

# I always enable full debuginfo, though debuginfo-lines is more important.
debuginfo = true

# Gives you line numbers for backtraces.
debuginfo-lines = true

# Using the system allocator (instead of jemalloc) means that tools
# like valgrind and memcache work better.
use-jemalloc = false

Running x.py and building a stage1 compiler

One thing to keep in mind is that rustc is a bootstrapping compiler. That is, since rustc is written in Rust, we need to use an older version of the compiler to compile the newer version. In particular, the newer version of the compiler, libstd, and other tooling may use some unstable features internally. The result is the compiling rustc is done in stages.

• Stage 0: the stage0 compiler is the current beta compiler; we download this binary from the internet.
• Stage 1: the code in your clone is then compiled with the stage 0 compiler to produce the stage 1 compiler.
• Stage 2: the code in your clone is then compiled with the stage 1 compiler again to produce the stage 2 compiler (i.e. it builds itself).

For hacking, often building the stage 1 compiler is enough, but for final testing and release, the stage 2 compiler is used.

Once you've created a config.toml, you are now ready to run x.py. There are a lot of options here, but let's start with what is probably the best "go to" command for building a local rust:

> ./x.py build -i --stage 1 src/libstd

What this command will do is the following:

• Using the beta compiler (also called stage 0), it will build the standard library and rustc from the src directory. The resulting compiler is called the "stage 1" compiler.
  • During this build, the -i (or --incremental) switch enables incremental compilation, so that if you later rebuild after editing things in src, you can save a bit of time.
• Using this stage 1 compiler, it will build the standard library. (this is what the src/libstd) means.

This is just a subset of the full rustc build. The full rustc build (what you get if you just say ./x.py build) has quite a few more steps:

• Build stage1 rustc with stage0 compiler.
• Build libstd with stage1 compiler (up to here is the same).
• Build rustc from src again, this time with the stage1 compiler (this part is new).
  • The resulting compiler here is called the "stage2" compiler.
• Build libstd with stage2 compiler.
• Build librustdoc and a bunch of other things.

Creating a rustup toolchain

Once you have successfully built rustc, you will have created a bunch of files in your build directory. In order to actually run the resulting rustc, we recommend creating rustup toolchains. The first one will run the stage1 compiler (which we built above). The second will execute the stage2 compiler (which we did not build, but which you will likely need to build at some point; for example, if you want to run the entire test suite).

> rustup toolchain link stage1 build/<host-triple>/stage1
> rustup toolchain link stage2 build/<host-triple>/stage2

Now you can run the rustc you built with. If you run with -vV, you should see a version number ending in -dev, indicating a build from your local environment:

> rustc +stage1 -vV
rustc 1.25.0-dev
binary: rustc
commit-hash: unknown
commit-date: unknown
host: x86_64-unknown-linux-gnu
release: 1.25.0-dev
LLVM version: 4.0

Other x.py commands

Here are a few other useful x.py commands. We'll cover some of them in detail in other sections:

• Building things:
  • ./x.py clean – clean up the build directory (rm -rf build works too, but then you have to rebuild LLVM)
  • ./x.py build --stage 1 – builds everything using the stage 1 compiler, not just up to libstd
  • ./x.py build – builds the stage2 compiler
• Running tests (see the section on running tests for more details):
  • ./x.py test --stage 1 src/libstd – runs the #[test] tests from libstd
  • ./x.py test --stage 1 src/test/run-pass – runs the run-pass test suite