Skip to content

Added info on the build system to contributing guide #31186

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jan 28, 2016
Merged

Added info on the build system to contributing guide #31186

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dc6ed63
Added info on the build system to contributing guide
gchp Jan 25, 2016
6fd728d
Updated to reflect comments from review
gchp Jan 26, 2016
05f7b59
Re-worded intro paragraph to be more positive
gchp Jan 26, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • "I" rubs me the wrong way, and above (line 45) "we" is used.
  • I wouldn't suggest anyone to try and understand everything about the build system, unless they specifically want to improve it (and if so, in the hopefully-near future that means improving on Add a Cargo-based build system to eventually replace make #31123 rather than fiddling with the Makefiles). Perhaps just give a non-prescriptive warning that it's massive and easy to get lost in and uses lots of advanced Make features.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rkruppe what about:

The build system for Rust is complex. It covers bootstrapping the compiler,
running tests, building documentation and more. It uses some advanced Make
features which can make it difficult to understand, and one can easily get
lost in it.

If Makefiles are your thing, though, all the configuration lives in
[the mk directory][mkdir] in the project root.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMHO "can easily get lost in it" is more a function of size than advancedness, but otherwise 👍

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What would you suggest as an alternative? Do you think it would be OK to cut that bit off, and leave it as

...advanced Make features which can make it difficult to understand.

?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Something like:

[...] building documentation and more.

If Makefiles are your thing, all the configuration [...] project root. It is easy to get lost though, as the build system is quite large and complex.

sounds more coherent to me.

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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might want to mention that --enable-debug --enable-optimized makes 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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Really minor nit but LLVM is not the only C/C++ dependency so this should read "(e.g., LLVM)"

- `--enable-ccache` - Invoke clang/gcc with ccache to re-use object files between builds
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For most contributors, --enable-compiler-docs is also quite useful.


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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personally I run check-stage1-coretest way more often than check-stage1-std. I may be biased because most of my library work ends up in libcore, but then again a huge chunk of the standard library consists of re-exports from core. Also worth mentioning because it deviates from the pattern of all other crates (i.e., check-stage1-core does not work).

rebuilding the entire compiler
- `make check TESTNAME=<path-to-test-file>.rs` - Run a single test file
- `make check-stage1-rpass TESTNAME=<path-to-test-file>.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
Expand Down