From d7c767835ccbee04a06dc49d01b19a9650eea2bb Mon Sep 17 00:00:00 2001 From: Rajkumar Natarajan Date: Thu, 6 Sep 2018 20:13:36 -0400 Subject: [PATCH 1/4] issue-130 copy contents related x.py from rust-forge --- src/build-install-distribution-artifacts.md | 27 +++++++++++ src/compiler-benchmarking.md | 11 +++++ src/compiler-documenting.md | 49 ++++++++++++++++++++ src/how-to-build-and-run.md | 51 ++++++++++++++++++++- src/tests/running.md | 23 ++++++++++ src/what-is-x-py.md | 42 +++++++++++++++++ 6 files changed, 201 insertions(+), 2 deletions(-) create mode 100644 src/build-install-distribution-artifacts.md create mode 100644 src/compiler-benchmarking.md create mode 100644 src/compiler-documenting.md create mode 100644 src/what-is-x-py.md diff --git a/src/build-install-distribution-artifacts.md b/src/build-install-distribution-artifacts.md new file mode 100644 index 000000000..472c074a3 --- /dev/null +++ b/src/build-install-distribution-artifacts.md @@ -0,0 +1,27 @@ +# 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: + + `./x.py dist` + +Other Flags + +The same flags from build are available here. +You might want to consider adding on the -j flag for faster builds +when building a distribution artifact. + +``` +-j, --jobs JOBS number of jobs to run in parallel +``` + + +# 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: + + `./x.py install` + +Other Flags +The same flags from build are available \ No newline at end of file diff --git a/src/compiler-benchmarking.md b/src/compiler-benchmarking.md new file mode 100644 index 000000000..1ce1e05ac --- /dev/null +++ b/src/compiler-benchmarking.md @@ -0,0 +1,11 @@ +# Benchmarking rustc + +This one is a easier compared to the others. +All you’re doing is running benchmarks of the compiler itself +so it’ll build it and run the one set of benchmarks available to it. +The command is: + + `./x.py bench` + +Benchmarking lacks `--no-fail-fast` flag that `test` command has. + \ No newline at end of file diff --git a/src/compiler-documenting.md b/src/compiler-documenting.md new file mode 100644 index 000000000..919914e98 --- /dev/null +++ b/src/compiler-documenting.md @@ -0,0 +1,49 @@ +# 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 or 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 + + `./x.py doc` + +## If you want to avoid the whole Stage 2 build + + `./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 +By default rustc does not build the compiler docs for its internal items. +Mostly because this is useless for the average user. However, you might need +to have it available so you can understand the types. Here’s how you can +compile it yourself. From the top level directory where x.py is located run: + + cp config.toml.example config.toml + +Next open up config.toml and make sure these two lines are set to true: + +docs = true +compiler-docs = true +When you want to build the compiler docs as well run this command: + + `./x.py doc` + +This will see that the docs and compiler-docs options are set to true +and build the normally hidden compiler docs! \ No newline at end of file diff --git a/src/how-to-build-and-run.md b/src/how-to-build-and-run.md index 66ba8efda..07a5eeb4d 100644 --- a/src/how-to-build-and-run.md +++ b/src/how-to-build-and-run.md @@ -134,6 +134,44 @@ build`) has quite a few more steps: +### Build different stages + + `./x.py build --stage 0` + + # Stage 1 is typically enough to test out all of your changes + # to the compiler + + `./x.py build --stage 1` + + # Equivalent to ./x.py build + + `./x.py build --stage 2` + +You can pass the --stage flag with what stage you want to build to. +It is recommended that you build to Stage 1 as this is enough to know +your changes can successfully compile and should let you run tests +with your changes. + +### Build specific components + + Build only the libcore library + + `./x.py build src/libcore` + + Build the libcore and libproc_macro library only + + `./x.py build src/libcore src/libproc_macro` + + Build only libcore up to Stage 1 + + `./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 @@ -145,8 +183,8 @@ you will likely need to build at some point; for example, if you want to run the entire test suite). ```bash -> rustup toolchain link stage1 build//stage1 -> rustup toolchain link stage2 build//stage2 + rustup toolchain link stage1 build//stage1 + rustup toolchain link stage2 build//stage2 ``` The `` would typically be one of the following: @@ -263,3 +301,12 @@ 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! + + `./x.py clean` \ No newline at end of file diff --git a/src/tests/running.md b/src/tests/running.md index 778fd00ec..970829cce 100644 --- a/src/tests/running.md +++ b/src/tests/running.md @@ -93,3 +93,26 @@ 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. +### Run specific tests + +# 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. diff --git a/src/what-is-x-py.md b/src/what-is-x-py.md new file mode 100644 index 000000000..315a3f821 --- /dev/null +++ b/src/what-is-x-py.md @@ -0,0 +1,42 @@ +# 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. + +### 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: + +``` +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 +``` + +Note that the options --incremental, --keep-stage 0 and --jobs JOBS can be +used in tandem with --stage to help reduce build times significantly by +reusing already built components, reusing the first bootstrapped stage, and +running compilation in parallel. To test changes you could run something like: + +```bash + ./x.py build --stage 1 --keep-stage 0 -j 4 -i +``` + +Please follow the links to build, document, test, benchmark and install +distribution + artifacts for rustc respectively. From 9633015c3cabdf67c5a7712f752598bdd8a799af Mon Sep 17 00:00:00 2001 From: Rajkumar Natarajan Date: Tue, 18 Sep 2018 17:29:59 -0400 Subject: [PATCH 2/4] issue-130 incorporate the review comments --- src/SUMMARY.md | 2 + src/build-install-distribution-artifacts.md | 15 ++-- src/compiler-documenting.md | 25 ++++-- src/how-to-build-and-run.md | 92 +++++++++++++++------ src/tests/running.md | 10 +-- src/what-is-x-py.md | 42 ---------- 6 files changed, 100 insertions(+), 86 deletions(-) delete mode 100644 src/what-is-x-py.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 338cb7fe1..213a645ab 100644 --- a/src/SUMMARY.md +++ b/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) diff --git a/src/build-install-distribution-artifacts.md b/src/build-install-distribution-artifacts.md index 472c074a3..89b1422a0 100644 --- a/src/build-install-distribution-artifacts.md +++ b/src/build-install-distribution-artifacts.md @@ -3,15 +3,17 @@ You might want to build and package up the compiler for distribution. You’ll want to run this command to do it: - `./x.py dist` + ```bash + ./x.py dist + ``` -Other Flags +## Other Flags The same flags from build are available here. You might want to consider adding on the -j flag for faster builds when building a distribution artifact. -``` +```bash -j, --jobs JOBS number of jobs to run in parallel ``` @@ -21,7 +23,6 @@ when building a distribution artifact. 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: - `./x.py install` - -Other Flags -The same flags from build are available \ No newline at end of file + ```bash + ./x.py install + ``` \ No newline at end of file diff --git a/src/compiler-documenting.md b/src/compiler-documenting.md index 919914e98..61d65f376 100644 --- a/src/compiler-documenting.md +++ b/src/compiler-documenting.md @@ -3,17 +3,21 @@ 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 or 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. + 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 - `./x.py doc` + ```bash + ./x.py doc + ``` ## If you want to avoid the whole Stage 2 build - `./x.py doc --stage 1` +```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. @@ -35,15 +39,22 @@ Mostly because this is useless for the average user. However, you might need to have it available so you can understand the types. Here’s how you can compile it yourself. From the top level directory where x.py is located run: - cp config.toml.example config.toml +```bash +cp config.toml.example config.toml +``` 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: - `./x.py doc` +```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! \ No newline at end of file diff --git a/src/how-to-build-and-run.md b/src/how-to-build-and-run.md index 07a5eeb4d..c11d269bd 100644 --- a/src/how-to-build-and-run.md +++ b/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,52 @@ 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 +``` + +One thing to keep in mind is that `rustc` is a _bootstrapping_ compiler. That +is, since `rustc` is written in Rust, we need to use an older version of the +compiler to compile the newer version. In particular, the newer version of the +compiler, `libstd`, and other tooling may use some unstable features +internally. The result is the compiling `rustc` is done in stages. + +- **Stage 0:** the stage0 compiler can be your existing + (perhaps older version of) + Rust compiler, the current _beta_ compiler or you may download the binary + from the internet. +- **Stage 1:** the code in your clone (for new version) + is then compiled with the stage0 + compiler to produce the stage1 compiler. + However, it was built with an older compiler (stage0), + so to optimize the stage1 compiler we go to next stage. +- **Stage 2:** we rebuild our stage1 compiler with itself + to produce the stage2 compiler (i.e. it builds + itself) to have all the _latest optimizations_. +- _(Optional)_ **Stage 3**: to sanity check of our new compiler, + we can build it again + with stage2 compiler which must be identical to itself, + unless something has broken. + For hacking, often building the stage 1 compiler is enough, but for final testing and release, the stage 2 compiler is used. @@ -134,37 +188,25 @@ build`) has quite a few more steps: -### Build different stages - - `./x.py build --stage 0` - - # Stage 1 is typically enough to test out all of your changes - # to the compiler - - `./x.py build --stage 1` - - # Equivalent to ./x.py build - - `./x.py build --stage 2` - -You can pass the --stage flag with what stage you want to build to. -It is recommended that you build to Stage 1 as this is enough to know -your changes can successfully compile and should let you run tests -with your changes. - ### Build specific components Build only the libcore library - `./x.py build src/libcore` +```bash +> ./x.py build src/libcore +``` Build the libcore and libproc_macro library only - `./x.py build src/libcore src/libproc_macro` +```bash +> ./x.py build src/libcore src/libproc_macro +``` Build only libcore up to Stage 1 - `./x.py build src/libcore --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 @@ -183,8 +225,8 @@ you will likely need to build at some point; for example, if you want to run the entire test suite). ```bash - rustup toolchain link stage1 build//stage1 - rustup toolchain link stage2 build//stage2 +> rustup toolchain link stage1 build//stage1 +> rustup toolchain link stage2 build//stage2 ``` The `` would typically be one of the following: @@ -309,4 +351,6 @@ 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! - `./x.py clean` \ No newline at end of file + ```bash + > ./x.py clean + ``` diff --git a/src/tests/running.md b/src/tests/running.md index 970829cce..07030c799 100644 --- a/src/tests/running.md +++ b/src/tests/running.md @@ -93,23 +93,21 @@ 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. -### Run specific tests - -# Run only the tidy script +### Run only the tidy script ```bash > ./x.py test src/tools/tidy ``` -# Run tests on the standard library +### Run tests on the standard library ```bash > ./x.py test src/libstd ``` -# Run tests on the standard library and run the tidy script +### 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 +### Run tests on the standard library using a stage 1 compiler ```bash > ./x.py test src/libstd --stage 1 ``` diff --git a/src/what-is-x-py.md b/src/what-is-x-py.md deleted file mode 100644 index 315a3f821..000000000 --- a/src/what-is-x-py.md +++ /dev/null @@ -1,42 +0,0 @@ -# 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. - -### 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: - -``` -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 -``` - -Note that the options --incremental, --keep-stage 0 and --jobs JOBS can be -used in tandem with --stage to help reduce build times significantly by -reusing already built components, reusing the first bootstrapped stage, and -running compilation in parallel. To test changes you could run something like: - -```bash - ./x.py build --stage 1 --keep-stage 0 -j 4 -i -``` - -Please follow the links to build, document, test, benchmark and install -distribution - artifacts for rustc respectively. From 9a3d5e6d6a26a4d31865d7fb62cd7669d4e9596c Mon Sep 17 00:00:00 2001 From: Rajkumar Natarajan Date: Wed, 26 Sep 2018 10:32:50 -0400 Subject: [PATCH 3/4] issue-130 updated the review comments --- src/build-install-distribution-artifacts.md | 20 +++------ src/compiler-benchmarking.md | 11 ----- src/compiler-documenting.md | 9 +--- src/how-to-build-and-run.md | 26 +---------- src/tests/running.md | 49 ++++++++++++--------- 5 files changed, 37 insertions(+), 78 deletions(-) delete mode 100644 src/compiler-benchmarking.md diff --git a/src/build-install-distribution-artifacts.md b/src/build-install-distribution-artifacts.md index 89b1422a0..521c441a2 100644 --- a/src/build-install-distribution-artifacts.md +++ b/src/build-install-distribution-artifacts.md @@ -7,22 +7,16 @@ You’ll want to run this command to do it: ./x.py dist ``` -## Other Flags - -The same flags from build are available here. -You might want to consider adding on the -j flag for faster builds -when building a distribution artifact. - -```bash --j, --jobs JOBS number of jobs to run in parallel -``` - - # Install distribution artifacts -If you’ve built a distribution artifact you might want to install it and +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 - ``` \ No newline at end of file + ``` + + 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 how-to-build-and-run.html#creating-a-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). \ No newline at end of file diff --git a/src/compiler-benchmarking.md b/src/compiler-benchmarking.md deleted file mode 100644 index 1ce1e05ac..000000000 --- a/src/compiler-benchmarking.md +++ /dev/null @@ -1,11 +0,0 @@ -# Benchmarking rustc - -This one is a easier compared to the others. -All you’re doing is running benchmarks of the compiler itself -so it’ll build it and run the one set of benchmarks available to it. -The command is: - - `./x.py bench` - -Benchmarking lacks `--no-fail-fast` flag that `test` command has. - \ No newline at end of file diff --git a/src/compiler-documenting.md b/src/compiler-documenting.md index 61d65f376..fceb73c91 100644 --- a/src/compiler-documenting.md +++ b/src/compiler-documenting.md @@ -34,14 +34,9 @@ Much like individual tests or building certain components you can build only the documentation you want. ## Document internal rustc items -By default rustc does not build the compiler docs for its internal items. -Mostly because this is useless for the average user. However, you might need -to have it available so you can understand the types. Here’s how you can -compile it yourself. From the top level directory where x.py is located run: -```bash -cp config.toml.example config.toml -``` +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: diff --git a/src/how-to-build-and-run.md b/src/how-to-build-and-run.md index c11d269bd..eb2f8a663 100644 --- a/src/how-to-build-and-run.md +++ b/src/how-to-build-and-run.md @@ -47,7 +47,7 @@ debuginfo-lines = true use-jemalloc = false ``` -### what is x.py? +### 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. @@ -88,7 +88,6 @@ 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 @@ -111,29 +110,6 @@ Options: -h, --help print this help message ``` -One thing to keep in mind is that `rustc` is a _bootstrapping_ compiler. That -is, since `rustc` is written in Rust, we need to use an older version of the -compiler to compile the newer version. In particular, the newer version of the -compiler, `libstd`, and other tooling may use some unstable features -internally. The result is the compiling `rustc` is done in stages. - -- **Stage 0:** the stage0 compiler can be your existing - (perhaps older version of) - Rust compiler, the current _beta_ compiler or you may download the binary - from the internet. -- **Stage 1:** the code in your clone (for new version) - is then compiled with the stage0 - compiler to produce the stage1 compiler. - However, it was built with an older compiler (stage0), - so to optimize the stage1 compiler we go to next stage. -- **Stage 2:** we rebuild our stage1 compiler with itself - to produce the stage2 compiler (i.e. it builds - itself) to have all the _latest optimizations_. -- _(Optional)_ **Stage 3**: to sanity check of our new compiler, - we can build it again - with stage2 compiler which must be identical to itself, - unless something has broken. - For hacking, often building the stage 1 compiler is enough, but for final testing and release, the stage 2 compiler is used. diff --git a/src/tests/running.md b/src/tests/running.md index 07030c799..f8889c8a4 100644 --- a/src/tests/running.md +++ b/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,25 +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. - -### 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. From 1c8097be3db524d76834624e29595684a964118c Mon Sep 17 00:00:00 2001 From: Rajkumar Natarajan Date: Fri, 28 Sep 2018 23:01:47 -0400 Subject: [PATCH 4/4] updated with review comments --- src/build-install-distribution-artifacts.md | 13 ++++++++++--- src/compiler-documenting.md | 3 ++- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/src/build-install-distribution-artifacts.md b/src/build-install-distribution-artifacts.md index 521c441a2..7430ffb9b 100644 --- a/src/build-install-distribution-artifacts.md +++ b/src/build-install-distribution-artifacts.md @@ -16,7 +16,14 @@ test that it works on your target system. You’ll want to run this command: ./x.py install ``` - Note: If you are testing out a modification to a compiler, you might want to use it to compile some project. + 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 how-to-build-and-run.html#creating-a-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). \ No newline at end of file + 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 \ No newline at end of file diff --git a/src/compiler-documenting.md b/src/compiler-documenting.md index fceb73c91..bf63c0120 100644 --- a/src/compiler-documenting.md +++ b/src/compiler-documenting.md @@ -35,7 +35,8 @@ Much like individual tests or building certain components you can build only ## Document internal rustc items -Compiler documentation is not built by default - there's a flag in config.toml for achieving the same. +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: