From c44964bd148d23a68f560a07c6d88117c564546a Mon Sep 17 00:00:00 2001 From: Niko Matsakis Date: Wed, 24 Jan 2018 09:11:24 -0500 Subject: [PATCH 1/2] how to build and run compiler, first shot --- src/how-to-build-and-run.md | 117 ++++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) diff --git a/src/how-to-build-and-run.md b/src/how-to-build-and-run.md index 505836094..de8a93bdd 100644 --- a/src/how-to-build-and-run.md +++ b/src/how-to-build-and-run.md @@ -1 +1,118 @@ # 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`: + +[`config.toml.example`]: https://github.com/rust-lang/rust/blob/master/config.toml.example + +```bash +> 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 + +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 --incremental --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 `--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 stage2 rustc with stage1 compiler (this part is new) +- 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 build at some point). + +``` +> rustup toolchain link stage1 build//stage1 +> rustup toolchain link stage2 build//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 [running tests](./running-tests.html) 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 From 3b142e54c23bf615eda3de5d1cd42289f86bcab0 Mon Sep 17 00:00:00 2001 From: Niko Matsakis Date: Thu, 25 Jan 2018 09:40:07 -0500 Subject: [PATCH 2/2] fix nits --- src/how-to-build-and-run.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/how-to-build-and-run.md b/src/how-to-build-and-run.md index de8a93bdd..f685f569c 100644 --- a/src/how-to-build-and-run.md +++ b/src/how-to-build-and-run.md @@ -19,7 +19,7 @@ To start, copy [`config.toml.example`] to `config.toml`: Then you will want to open up the file and change the following settings (and possibly others, such as `llvm.ccache`): -``` +```toml [llvm] # Enables LLVM assertions, which will check that the LLVM bitcode generated # by the compiler is internally consistent. These are particularly helpful @@ -53,7 +53,7 @@ Once you've created a config.toml, you are now ready to run probably the best "go to" command for building a local rust: ``` -./x.py build --incremental --stage 1 src/libstd +./x.py build -i --stage 1 src/libstd ``` What this command will do is the following: @@ -61,7 +61,7 @@ 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 `--incremental` switch enables incremental + - 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. @@ -72,7 +72,8 @@ 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 stage2 rustc with stage1 compiler (this part is new) +- 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 @@ -83,7 +84,8 @@ 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 build at some point). +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//stage1