From fca1fd0034fccca989aeb611c888d82048cb0e96 Mon Sep 17 00:00:00 2001 From: Nilstrieb <48135649+Nilstrieb@users.noreply.github.com> Date: Sat, 30 Mar 2024 17:31:54 +0100 Subject: [PATCH 1/2] Add quickstart for how to build and run the compiler The chapter is quite long, and a lot of the information is, while valuable, not very important for newcomers. I think it makes sense to have a condensed version for anyone just wanting to get started with only the most important information. --- src/SUMMARY.md | 1 + src/building/how-to-build-and-run.md | 5 +++ src/building/quickstart.md | 60 ++++++++++++++++++++++++++++ 3 files changed, 66 insertions(+) create mode 100644 src/building/quickstart.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index a4be4b929..0e983748f 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -8,6 +8,7 @@ # Building and debugging `rustc` - [How to build and run the compiler](./building/how-to-build-and-run.md) + - [Quickstart](./building/quickstart.md) - [Prerequisites](./building/prerequisites.md) - [Suggested Workflows](./building/suggested.md) - [Distribution artifacts](./building/build-install-distribution-artifacts.md) diff --git a/src/building/how-to-build-and-run.md b/src/building/how-to-build-and-run.md index 33ac97010..336135978 100644 --- a/src/building/how-to-build-and-run.md +++ b/src/building/how-to-build-and-run.md @@ -5,6 +5,11 @@ The compiler is built using a tool called `x.py`. You will need to have Python installed to run it. +## Quick Start + +For a less in-depth quick-start of getting the compiler running, see [quickstart](./quickstart.md). + + ## Get the source code The main repository is [`rust-lang/rust`][repo]. This contains the compiler, diff --git a/src/building/quickstart.md b/src/building/quickstart.md new file mode 100644 index 000000000..18b993065 --- /dev/null +++ b/src/building/quickstart.md @@ -0,0 +1,60 @@ +# Quickstart + +This is a quickstart guide about getting the compiler running. For more information in the individual steps, +see the other pages in this chapter. + +First, clone the repository: + +```sh +git clone https://github.com/rust-lang/rust.git +cd rust +``` + +When building the compiler, we don't use `cargo` directly, instead we use a wrapper called "x". +On Unix-like platforms, use `./x`. On Windows, use `.\x.ps1`. This guide will use `./x`. + +We need to create a configuration for the build. Use `./x setup` to create a good default. + +```sh +./x setup +``` + +Then, we can build the compiler. Use `./x build` to build the compiler, standard library and a few tools. +You can also `./x check` to just check it. +All these commands can take specific components/paths as arguments, for example `./x check compiler` to just check the compiler. + +```sh +./x build +``` + +> When doing a change to the compiler that does not affect the way it compiles the standard library +(so for example, a change to an error message), use `--keep-stage-std 1` to avoid recompiling it. + +After building the compiler and standard library, you now have a working compiler toolchain. +You can use it with rustup by linking it. + +```sh +rustup toolchain link stage1 build/host/stage1 +``` + +Now you have a toolchain called `stage1` linked to your build. You can use it to test the compiler. + +```sh +rustc +stage testfile.rs +``` + +After doing a change, you can run the compiler test suite with `./x test`. + +`./x test` runs the full test suite, which is slow and rarely what you want. +Usually, `./x test tests/ui` is what you want after a comiler change, +testing all "UI" tests that invoke the compiler on a specific test file and check the output. + +```sh +./x test tests/ui +``` + +> `./x suggest` can also be helpful for suggesting which tests to run after a change. + +Congrats, you are now ready to make a change to the compiler! If you have more questions, +[the full chapter](./how-to-build-and-run.md) might contain the answers, and if it doesn't, +feel free to ask for help on [Zulip](https://rust-lang.zulipchat.com/#narrow/stream/182449-t-compiler.2Fhelp). \ No newline at end of file From f2e924d02041f46f14c0982f69a2f9ba19f0f6f2 Mon Sep 17 00:00:00 2001 From: Nilstrieb <48135649+Nilstrieb@users.noreply.github.com> Date: Sat, 30 Mar 2024 17:47:31 +0100 Subject: [PATCH 2/2] A few improvements to quickstart --- src/building/quickstart.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/src/building/quickstart.md b/src/building/quickstart.md index 18b993065..9c90b1dbb 100644 --- a/src/building/quickstart.md +++ b/src/building/quickstart.md @@ -11,7 +11,7 @@ cd rust ``` When building the compiler, we don't use `cargo` directly, instead we use a wrapper called "x". -On Unix-like platforms, use `./x`. On Windows, use `.\x.ps1`. This guide will use `./x`. +It is invoked with `./x`. We need to create a configuration for the build. Use `./x setup` to create a good default. @@ -40,21 +40,25 @@ rustup toolchain link stage1 build/host/stage1 Now you have a toolchain called `stage1` linked to your build. You can use it to test the compiler. ```sh -rustc +stage testfile.rs +rustc +stage1 testfile.rs ``` After doing a change, you can run the compiler test suite with `./x test`. `./x test` runs the full test suite, which is slow and rarely what you want. Usually, `./x test tests/ui` is what you want after a comiler change, -testing all "UI" tests that invoke the compiler on a specific test file and check the output. +testing all [UI tests](../tests/ui.md) that invoke the compiler on a specific test file and check the output. ```sh ./x test tests/ui ``` +Use `--bless` if you've made a change and want to update the `.stderr` files with the new output. + > `./x suggest` can also be helpful for suggesting which tests to run after a change. Congrats, you are now ready to make a change to the compiler! If you have more questions, [the full chapter](./how-to-build-and-run.md) might contain the answers, and if it doesn't, -feel free to ask for help on [Zulip](https://rust-lang.zulipchat.com/#narrow/stream/182449-t-compiler.2Fhelp). \ No newline at end of file +feel free to ask for help on [Zulip](https://rust-lang.zulipchat.com/#narrow/stream/182449-t-compiler.2Fhelp). + +If you use VSCode, `./x setup` will ask you if you want to set up the config. For other editors, check out [suggested workflows](./suggested.md).