diff --git a/src/build-install-distribution-artifacts.md b/src/build-install-distribution-artifacts.md index 89b1422a..521c441a 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 1ce1e05a..00000000 --- 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 61d65f37..fceb73c9 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 c11d269b..eb2f8a66 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 07030c79..f8889c8a 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.