Added info on the build system to contributing guide #31186
Conversation
|
Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @alexcrichton (or someone else) soon. If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes. Please see the contribution instructions for more information. |
|
As mentioned in the commit message, this is by no means a full guide to the build system. If there are any pieces you feel should be added to this, please let me know. Hopefully you find it useful! |
| [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 |
There was a problem hiding this comment.
could you put a newline above here, like with the other headings?
|
One small nit, this looks good to me, but I'm terrible with the build system, so would like someone else to review too. |
|
@steveklabnik updated! |
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.
|
|
||
| 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 |
There was a problem hiding this comment.
- "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.
There was a problem hiding this comment.
@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
[themkdirectory][mkdir] in the project root.
There was a problem hiding this comment.
IMHO "can easily get lost in it" is more a function of size than advancedness, but otherwise 👍
There was a problem hiding this comment.
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.
?
There was a problem hiding this comment.
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.
|
@rkruppe I've updated to reflect your comments. I tweaked the intro paragraph a little more, let me know what you think. Thank you for your feedback. |
| 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. Running `make help` and `make tips` might be useful when |
There was a problem hiding this comment.
This document already contains some of the information of make help and what's not in here is not very helpful for build system hacking. I would point towards make nitty-gritty but I have no idea if it's even remotely up to date. Perhaps cut the false reassurance of documentation and just point people towards #rust-internals.
There was a problem hiding this comment.
Fair point. Will update now.
- Tweaked the build system intro paragraph - Added some more configure options & explanations - Added additional make target
| ## The Build System | ||
|
|
||
| The build system for Rust is complex. It covers bootstrapping the compiler, | ||
| running tests, building documentation and more. |
There was a problem hiding this comment.
This should have occurred to me sooner, but since this section spends most of its text on how scary the build system is, perhaps the opening paragraph should not mention the complexity at all and instead include some re-assuring words. Something like
Rust's build system allows you to bootstrap the compiler, run tests and benchmarks, generate documentation, install your freshly-built rust, and more. It's your best friend when working on Rust, allowing you to try out your contributions before submitting them.
(edit: significantly reworded that text)
There was a problem hiding this comment.
Haha, right. Probably a good thing to not just spend time scaring people :)
|
Awesome 👍 Thanks for doing this, the build system was by far the part I fought with the most when getting started. I'm still no expert but as far as I am concerned this is good to go. |
|
@rkruppe thanks! Not sure why the build is failing all of a sudden...seems very unlikely that this would cause it to fail? |
|
I really doubt that this has anything to do with your changes. Travis logs indicate it fails to add a PPA and subsequently can't install some package. Four hours ago, in #31212, the same build commands succeeded so this may be outside of our control. |
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.
|
⌛ Testing commit 05f7b59 with merge 6d0fbfd... |
|
💔 Test failed - auto-linux-64-x-android-t |
|
@bors: retry On Wed, Jan 27, 2016 at 12:16 PM, bors notifications@github.com wrote:
|
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.