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 can be your existing (perhaps older version of) Rust compiler, the current beta compiler or you may download the binary from the internet.
• Stage 1: the code in your clone (for new version) is then compiled with the stage0 compiler to produce the stage1 compiler. However, it was built with an older compiler (stage0), so to optimize the stage1 compiler we go to next stage.
• Stage 2: we rebuild our stage1 compiler with itself to produce the stage2 compiler (i.e. it builds itself) to have all the latest optimizations.
• (Optional) Stage 3: to sanity check of our new compiler, we can build it again with stage2 compiler which must be identical to itself, unless something has broken.

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

./x.py check is really fast to build the rust compiler. It is, in particular, very useful when you're doing some kind of "type-based refactoring", like renaming a method, or changing the signature of some function.

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