"How to build the compiler and run what you built"

[nikomatsakis]

This section should describe how to build the compiler and run what you built. There is plenty of existing material that we can draw on. For example, the build system section of the CONTRIBUTING.md file covers similar material.

One thing that I think is missing from existing material is a focus on "practical recipes". Here are the highlights I would mention:

config.toml

First thing first, create a config.toml with the following options enabled:
- debug-assertions = true -- enables debug logs (as well as additional assertions)
- debuginfo-lines = true -- get line-number information
- use-jemalloc = false -- this means that tools like valgrind work better; it also decreases peak memory usage
- (any other suggestions? perhaps something to enable LLVM assertions, if that is needed now?)

• Some options you may want:
  • ccache = true -- ❓ helps speed up builds, you may need to install ccache first though
  • debug = true -- ❓ I turn this one, but really all that is useful I think is line number information

How to run compiler and enable debug logs

• I would recommend setting up a rustup toolchain for stage1 and stage2
  • that means you can do rustc +stage1 ... and rustc +stage2 ... to run the compiler you've built
• Talk about how to use the RUST_LOG environment variable
  • example: RUST_LOG=rustc::infer rustc +stage1 foo.rs >& killme will dump all the debug logs from the the infer module of the rustc crate.
• Mention that there are -Z flags useful for debugging and others things (and direct to #11)

Useful commands and targets for ./x.py:

./x.py build

Builds everything. This is very slow, and you won't want to run it a lot. Ultimately this builds the compiler with the beta compiler -- kind of roughly giving you the nightly compiler. It then builds the compiler again, using that nightly compiler (to check that it can build itself, and to resolve some annoying issues around linking).

./x.py build --stage 1 src/libstd or ./x.py build --incremental src/libstd

These commands will build a working stage1 rustc and standard library. The output can be found in build/<target>/stage1/bin/rustc. It's the fastest way to get a working compiler.

It may be somewhat surprising that this command builds the compiler, since it says to build src/libstd (the standard library). The reason for this is that we are building the compiler once (the stage1 compiler) and then using that compiler to build the stage1 standard library. This will be the standard library that your compiled programs will use.

I guess we can omit the ./x.py test routines for the next section.

What else?

Maybe leave some thoughts in the comments below on things you would have liked to know?