move over the rustc README

[nikomatsakis]

There is a lot of existing content scattered in READMEs through rustc. We should move over that content. To start, the rustc README is a good candiate. It desribes the layout of the crates and contains a glossary (oh, we should probably add the glossary to its own chapter).

EDIT(@mark-i-m): Added TODOs

EDIT2(@mark-i-m): A lot of the content of the READMEs is redundant with content we already have, so please check that the content you are moving over is not already in the appropriate chapter. If it is, please post here, so we can check it off the list 😄

TODOs:

• Overall arch: https://github.com/rust-lang/rust/blob/master/src/librustc/README.md
• Dependency tracking/Incr. Compl.: https://github.com/rust-lang/rust/blob/master/src/librustc/dep_graph/README.md
  • Actually, I think the chapter in this book is more up-to-date than the README, which doesn't have red-green in it... There is some info in the READMEs, such as testing and debugging, that is not TMK in the book yet. - @mark-i-m
  • See Dependency tracking README outdated? rust#47935
  • See advice for debugging incremental compilation hashing failures etc #87
  • See Add incremental compilation debugging subchapter #92
• HIR: https://github.com/rust-lang/rust/blob/master/src/librustc/hir/README.md
• Type Inference: https://github.com/rust-lang/rust/blob/master/src/librustc/infer/README.md (Copy type inference readme #31)
• MIR: https://github.com/rust-lang/rust/blob/master/src/librustc/mir/README.md (Copy MIR readme #36)
• Trait resolution: https://github.com/rust-lang/rust/blob/master/src/librustc/traits/README.md
• The ty module: https://github.com/rust-lang/rust/blob/master/src/librustc/ty/README.md
• ./src/librustc/infer/region_constraints/README.md
  • I'm not sure we want to move this one over since it will soon be obsolete. rework and vastly expand the MIR section #67 describes the new system (NLL). (Agreed -@nikomatsakis)
• ./src/librustc/infer/lexical_region_resolve/README.md
  • Same here (Agreed -@nikomatsakis)
• ./src/librustc/infer/higher_ranked/README.md
  • Skolemization (rework and vastly expand the MIR section #67) -- This material is different from what is covered in the rustc-guide, because the rustc-guide is describing the newer system we are aiming to add, and this is covering the older system we currently use. (-@nikomatsakis)
  • LUB/GLB -- same here (-@nikomatsakis)
• ./src/librustc/ty/maps/README.md
• ./src/librustc_data_structures/obligation_forest/README.md
  • (I probably wouldn't move this over either. -@nikomatsakis)
• ./src/librustc_typeck/variance/README.md (Add the contents of the typeck READMEs #85)
• ./src/librustc_typeck/check/method/README.md (Add the contents of the typeck READMEs #85)
• ./src/librustc_typeck/README.md (Add the contents of the typeck READMEs #85)
• ./src/librustc_borrowck/borrowck/README.md
  • This too is basically obsolete. The NLL RFC offers better coverage of the new-and-shiny borrow checker, and we should add more of that material, I think. -@nikomatsakis
• Rustdoc README from add readme for librustdoc rust#48283 (Add the rustdoc readme #86 )

[mark-i-m]

@nikomatsakis What is the status of the README about dependency tracking... is there any content there that needs to be moved over to the book still?

[nikomatsakis]

@mark-i-m good question. I'm not entirely sure how much of that material is still relevant.

[mark-i-m]

cc @michaelwoerister ?

[mark-i-m]

I'm going to go ahead and close this. We can augment the dep. tracking chapters later if we want.

[mark-i-m]

It looks like there are a few more to do... updated the list above.

[mark-i-m]

@nikomatsakis Is ./src/librustc_borrowck/borrowck/README.md still relevant?

[mark-i-m]

also, do we want to move over ./src/librustc/infer/region_constraints/README.md and ./src/librustc/infer/lexical_region_resolve/README.md which describe the old region inference system?

[mark-i-m]

After #92 this will be done 🎉

[mark-i-m]

🎉