From dc6ed63655b6698828b363e49d6bd9df76633334 Mon Sep 17 00:00:00 2001 From: Greg Chapple Date: Mon, 25 Jan 2016 14:07:10 +0000 Subject: [PATCH 1/3] Added info on the build system to contributing guide I recently wrote a blog post on contributing to the Rust compiler which gained some interest. It was mentioned in a comment on Reddit that it would be useful to integrate some of the information from that post to the official contributing guide. This is the start of my efforts to integrate what I wrote with the official guide. This commit adds information on the build system. It is not a complete guide on the build system, but it should be enough to provide a good starting place for those wishing to contribute. --- CONTRIBUTING.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e864172e81332..94576bbac1f2c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,6 +6,7 @@ links to the major sections: * [Feature Requests](#feature-requests) * [Bug Reports](#bug-reports) +* [The Build System](#the-build-system) * [Pull Requests](#pull-requests) * [Writing Documentation](#writing-documentation) * [Issue Triage](#issue-triage) @@ -77,6 +78,60 @@ to do this is to invoke `rustc` like this: $ RUST_BACKTRACE=1 rustc ... ``` +## The Build System + +The build system for Rust is complex. It covers bootstrapping the compiler, +running tests, building documentation and more. Unless you are familiar with +Makefiles, I wouldn't suggest trying to understand everything going on in +Rust's setup - there's a lot there, and you can get lost trying to understand +it all. + +If Makefiles are your thing, though, all the configuration lives in +[the `mk` directory][mkdir] in the project root. + +[mkdir]: https://github.com/rust-lang/rust/tree/master/mk/ + +### Configuration + +Before you can start building the compiler you need to configure the build for +your system. In most cases, that will just mean using the defaults provided +for Rust. Configuring involves invoking the `configure` script in the project +root. + +``` +./configure +``` + +There are large number of options accepted by this script to alter the +configuration used later in the build process. Some options to note: + +- `--enable-debug` - Build a debug version of the compiler (disables optimizations) +- `--disable-valgrind-rpass` - Don't run tests with valgrind +- `--enable-clang` - Prefer clang to gcc for building dependencies (ie LLVM) +- `--enable-ccache` - Invoke clang/gcc with ccache to re-use object files between builds + +To see a full list of options, run `./configure --help`. + +### Useful Targets + +Some common make targets are: + +- `make rustc-stage1` - build up to (and including) the first stage. For most + cases we don't need to build the stage2 compiler, so we can save time by not + building it. The stage1 compiler is a fully functioning compiler and + (probably) will be enough to determine if your change works as expected. +- `make check` - build the full compiler & run all tests (takes a while). This + is what gets run by the continuous integration system against your pull + request. You should run this before submitting to make sure your tests pass + & everything builds in the correct manner. +- `make check-stage1-std NO_REBUILD=1` - test the standard library without + rebuilding the entire compiler +- `make check TESTNAME=.rs` - Run a single test file +- `make check-stage1-rpass TESTNAME=.rs` - Run a single + rpass test with the stage1 compiler (this will be quicker than running the + command above as we only build the stage1 compiler, not the entire thing). + You can also leave off the `-rpass` to run all stage1 test types. + ## Pull Requests Pull requests are the primary mechanism we use to change Rust. GitHub itself From 6fd728db6d062a18887b4a0ee5af9aa6215593ce Mon Sep 17 00:00:00 2001 From: Greg Chapple Date: Tue, 26 Jan 2016 14:14:09 +0000 Subject: [PATCH 2/3] Updated to reflect comments from review - Tweaked the build system intro paragraph - Added some more configure options & explanations - Added additional make target --- CONTRIBUTING.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 94576bbac1f2c..e3d5fb83e37a2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -81,13 +81,13 @@ $ RUST_BACKTRACE=1 rustc ... ## The Build System The build system for Rust is complex. It covers bootstrapping the compiler, -running tests, building documentation and more. Unless you are familiar with -Makefiles, I wouldn't suggest trying to understand everything going on in -Rust's setup - there's a lot there, and you can get lost trying to understand -it all. +running tests, building documentation and more. -If Makefiles are your thing, though, all the configuration lives in -[the `mk` directory][mkdir] in the project root. +If Makefiles are your thing, all the configuration lives in +[the `mk` directory][mkdir] in the project root. Is can be hard to follow +in places, as it uses some advanced Make features which make for some +challenging reading. If you have questions on the build system internals, try +asking in [`#rust-internals`][pound-rust-internals]. [mkdir]: https://github.com/rust-lang/rust/tree/master/mk/ @@ -106,9 +106,12 @@ There are large number of options accepted by this script to alter the configuration used later in the build process. Some options to note: - `--enable-debug` - Build a debug version of the compiler (disables optimizations) +- `--enable-optimize` - Enable optimizations (can be used with `--enable-debug` + to make a debug build with optimizations) - `--disable-valgrind-rpass` - Don't run tests with valgrind -- `--enable-clang` - Prefer clang to gcc for building dependencies (ie LLVM) +- `--enable-clang` - Prefer clang to gcc for building dependencies (e.g., LLVM) - `--enable-ccache` - Invoke clang/gcc with ccache to re-use object files between builds +- `--enable-compiler-docs` - Build compiler documentation To see a full list of options, run `./configure --help`. @@ -131,6 +134,7 @@ Some common make targets are: rpass test with the stage1 compiler (this will be quicker than running the command above as we only build the stage1 compiler, not the entire thing). You can also leave off the `-rpass` to run all stage1 test types. +- `make check-stage1-coretest` - Run stage1 tests in `libcore`. ## Pull Requests From 05f7b59352abe51f4b1b4897dfcdae7feb33a3a3 Mon Sep 17 00:00:00 2001 From: Greg Chapple Date: Tue, 26 Jan 2016 14:41:29 +0000 Subject: [PATCH 3/3] Re-worded intro paragraph to be more positive --- CONTRIBUTING.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e3d5fb83e37a2..e4870aa6a8980 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -80,14 +80,16 @@ $ RUST_BACKTRACE=1 rustc ... ## The Build System -The build system for Rust is complex. It covers bootstrapping the compiler, -running tests, building documentation and more. - -If Makefiles are your thing, all the configuration lives in -[the `mk` directory][mkdir] in the project root. Is can be hard to follow -in places, as it uses some advanced Make features which make for some -challenging reading. If you have questions on the build system internals, try -asking in [`#rust-internals`][pound-rust-internals]. +Rust's build system allows you to bootstrap the compiler, run tests & +benchmarks, generate documentation, install a fresh build of Rust, and more. +It's your best friend when working on Rust, allowing you to compile & test +your contributions before submission. + +All the configuration for the build system lives in [the `mk` directory][mkdir] +in the project root. It can be hard to follow in places, as it uses some +advanced Make features which make for some challenging reading. If you have +questions on the build system internals, try asking in +[`#rust-internals`][pound-rust-internals]. [mkdir]: https://github.com/rust-lang/rust/tree/master/mk/