Update librustc README to include info on compiler process #31132
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. |
|
I expect there will be many iterations of this before it is merged, so do please let me know your comments. Also, if you would prefer me to submit in larger chunks, rather than section by section, let me know too! cc. @brson & @steveklabnik Update: Rendered version of the overview |
|
Thanks @gchp. This is really cool. This would be somewhere to direct new contributors to learn about the source code. It would need to replace. Note that there are already files in the source tree that describe the source:
It's of varying quality, but some of the specifics are particularly good. So the compiler documentation needs to integrate all this existing material. That's part of why I'll suggest that this particular book format is not the best format for source code documentation: it's nice to be able to browse the long-form documentation next to the source it refers to. This is especially true on github where each directory you open gives you a readme of what you are in for. Having the docs next to the source makes it easier for the devs, who need like it and maintain it, to keep it up to date, since it's part of the the corner of the product they care about and not an independent resource. So as the format for this book I suggest we take advantage of GitHub's nice browability to unify all these internal documents into a complete experience: make them all follow consistent conventions, hyperlink them together, create entry page in src/, fill out missing information useful to newbies. Organizationally, I suggest that this overview needs to replace librustc/README.md, while incorporating any useful information already there. I suspect the @rust-lang/compiler team will have opinions about how the source is documented. |
|
|
||
| The Rust compiler is a complex project. Upon first inspection, it can be a | ||
| daunting task to attempt to understand all the various crates & modules, the | ||
| flow of data and the internal data structures. |
There was a problem hiding this comment.
missing an oxford comma here
|
I think @brson's organisational plan sounds good. I'm keen for src/librustc/README.md to be improved, in particular. |
| output of this phase is an abstract syntax tree (AST). The AST at this point | ||
| includes all macro uses & attributes. This means code which will be later | ||
| expanded and/or removed due to `cfg` attributes is still present in this | ||
| version of the AST. Parsing abstracts away details about individual fies which |
|
Before looking things over: thanks so much for spearheading this. I am pretty horrific at compiler internals because, well, I write docs all day :) This work is so, so appreciated. |
|
@brson thanks for the feedback! I want this to be useful, so I'm happy to update this to whatever format the team feels would be best. I'll take what I have here and integrate it with what is already in Should get this PR updated shortly. I'll be sure to update with feedback from @jonas-schievink & @rphmeier too. |
|
Ok, I've moved what I had into the README in |
gchp
changed the title
|
Hey everyone, just wondering if there are any comments on this? |
|
Mine is 👍 |
|
Thanks @steveklabnik! @brson - is this closer to what you were thinking? |
|
📌 Commit 88d5bfd has been approved by |
This adds the basic structure for the internals documentation, and also the initial version of the "Overview". This first section gives and overview of the compilation process. It mentions the individual phases, and gives mention to their function & links to the relevant crates in the source tree. This is a very general overview which is meant to lead in to the next section which will cover the `driver`. That section will give more in-depth information on each of the phases & cover things like sessions and the driver API. I wanted to give a more general introduction before getting into that detail.
This adds the basic structure for the internals documentation, and also the initial version of the "Overview".
This first section gives and overview of the compilation process. It mentions the individual phases, and gives mention to their function & links to the relevant crates in the source tree.
This is a very general overview which is meant to lead in to the next section which will cover the
driver. That section will give more in-depth information on each of the phases & cover things like sessions and the driver API. I wanted to give a more general introduction before getting into that detail.