issue-130 copy contents related x.py from rust-forge to rustc-guide

src/SUMMARY.md

@@ -3,6 +3,8 @@
 - [About this guide](./about-this-guide.md)
 - [About the compiler team](./compiler-team.md)
 - [How to build the compiler and run what you built](./how-to-build-and-run.md)
+    - [Build and Install distribution artifacts](./build-install-distribution-artifacts.md)
+    - [Documenting Compiler](./compiler-documenting.md)
 - [Coding conventions](./conventions.md)
 - [Walkthrough: a typical contribution](./walkthrough.md)
 - [The compiler testing framework](./tests/intro.md)

src/build-install-distribution-artifacts.md

@@ -0,0 +1,29 @@
+# Build distribution artifacts
+
+You might want to build and package up the compiler for distribution.
+You’ll want to run this command to do it:
+
+   ```bash
+   ./x.py dist
+   ```
+
+# Install distribution artifacts
+
+If you’ve built a distribution artifact you might want to install it and
+test that it works on your target system. You’ll want to run this command:
+
+   ```bash
+   ./x.py install
+   ```
+
+   Note: If you are testing out a modification to a compiler, you
+   might want to use it to compile some project.
+   Usually, you do not want to use ./x.py install for testing.
+   Rather, you should create a toolchain as discussed in
+   [here][create-rustup-toolchain].
+
+   For example, if the toolchain you created is called foo, you
+   would then invoke it with `rustc +foo ...` (where ... represents
+   the rest of the arguments).
+
+[create-rustup-toolchain]: ./how-to-build-and-run.md#creating-a-rustup-toolchain

src/compiler-documenting.md

@@ -0,0 +1,56 @@
+# Documenting rustc
+
+You might want to build documentation of the various components 
+available like the standard library. There’s two ways to go about this.
+ You can run rustdoc directly on the file to make sure the HTML is 
+ correct, which is fast. Alternatively, you can build the documentation 
+ as part of the  build process through x.py. Both are viable methods 
+ since documentation  is more about the content.
+
+## Document everything
+
+   ```bash
+   ./x.py doc
+   ```
+
+## If you want to avoid the whole Stage 2 build
+
+```bash
+./x.py doc --stage 1
+```
+
+First the compiler and rustdoc get built to make sure everything is okay 
+and then it documents the files.
+
+## Document specific components
+
+```bash
+   ./x.py doc src/doc/book
+   ./x.py doc src/doc/nomicon
+   ./x.py doc src/doc/book src/libstd
+```
+
+Much like individual tests or building certain components you can build only
+ the documentation you want.
+
+## Document internal rustc items
+
+Compiler documentation is not built by default. There's a flag in
+config.toml for achieving the same.
+But, when enabled, compiler documentation does include internal items.
+
+Next open up config.toml and make sure these two lines are set to true:
+
+```bash
+docs = true
+compiler-docs = true
+```
+
+When you want to build the compiler docs as well run this command:
+
+```bash
+./x.py doc
+```
+
+This will see that the docs and compiler-docs options are set to true 
+and build the normally hidden compiler docs!

src/how-to-build-and-run.md

@@ -47,6 +47,14 @@ debuginfo-lines = true
 use-jemalloc = false
 ```
 
+### What is x.py?
+
+x.py is the script used to orchestrate the tooling in the rustc repository. 
+It is the script that can build docs, run tests, and compile rustc. 
+It is the now preferred way to build rustc and it replaces the old makefiles 
+from before. Below are the different ways to utilize x.py in order to 
+effectively deal with the repo for various common tasks.
+
 ### Running x.py and building a stage1 compiler
 
 One thing to keep in mind is that `rustc` is a _bootstrapping_
@@ -80,6 +88,28 @@ compiling `rustc` is done in stages:
   can build the libraries with the stage2 compiler. The result ought
   to be identical to before, unless something has broken.
 
+#### Build Flags
+
+There are other flags you can pass to the build portion of x.py that can be 
+beneficial to cutting down compile times or fitting other things you might 
+need to change. They are:
+
+```bash
+Options:
+    -v, --verbose       use verbose output (-vv for very verbose)
+    -i, --incremental   use incremental compilation
+        --config FILE   TOML configuration file for build
+        --build BUILD   build target of the stage0 compiler
+        --host HOST     host targets to build
+        --target TARGET target targets to build
+        --on-fail CMD   command to run on failure
+        --stage N       stage to build
+        --keep-stage N  stage to keep without recompiling
+        --src DIR       path to the root of the rust checkout
+    -j, --jobs JOBS     number of jobs to run in parallel
+    -h, --help          print this help message
+```
+
 For hacking, often building the stage 1 compiler is enough, but for
 final testing and release, the stage 2 compiler is used.
 
@@ -134,6 +164,32 @@ build`) has quite a few more steps:
 
 <a name=toolchain></a>
 
+### Build specific components
+
+   Build only the libcore library
+
+```bash
+> ./x.py build src/libcore
+```
+
+   Build the libcore and libproc_macro library only
+
+```bash
+> ./x.py build src/libcore src/libproc_macro
+```
+
+   Build only libcore up to Stage 1
+
+```bash
+> ./x.py build src/libcore --stage 1
+```
+
+Sometimes you might just want to test if the part you’re working on can 
+compile. Using these commands you can test that it compiles before doing 
+a bigger build to make sure it works with the compiler. As shown before 
+you can also pass flags at the end such as --stage.
+
+
 ### Creating a rustup toolchain
 
 Once you have successfully built rustc, you will have created a bunch
@@ -263,3 +319,14 @@ This allows you to do "jump-to-def" with whatever functions were around when
 you last built, which is ridiculously useful.
 
 [etags]: https://github.com/nikomatsakis/rust-etags
+
+### Cleaning out build directories
+
+Sometimes you need to start fresh, but this is normally not the case. 
+If you need to run this then rustbuild is most likely not acting right and 
+you should file a bug as to what is going wrong. If you do need to clean 
+everything up then you only need to run one command!
+
+   ```bash
+   > ./x.py clean
+   ```

src/tests/running.md

@@ -40,6 +40,33 @@ the debuginfo test suite:
 > ./x.py test --stage 1 src/test/debuginfo
 ```
 
+### Run only the tidy script
+
+```bash
+> ./x.py test src/tools/tidy
+```
+
+### Run tests on the standard library
+
+```bash
+> ./x.py test src/libstd
+```
+
+### Run tests on the standard library and run the tidy script
+
+```bash
+> ./x.py test src/libstd src/tools/tidy
+```
+
+### Run tests on the standard library using a stage 1 compiler
+
+```bash
+>   ./x.py test src/libstd --stage 1
+```
+
+By listing which test suites you want to run you avoid having to run
+tests for components you did not change at all.
+
 **Warning:** Note that bors only runs the tests with the full stage 2
 build; therefore, while the tests **usually** work fine with stage 1,
 there are some limitations. In particular, the stage1 compiler doesn't
@@ -92,4 +119,3 @@ just `rs` files, so you can do something like
 This is much faster, but doesn't always work. For example, some tests
 include directives that specify specific compiler flags, or which rely
 on other crates, and they may not run the same without those options.
-