diff --git a/src/building/quickstart.md b/src/building/quickstart.md index ba55f2124..9a8ab353e 100644 --- a/src/building/quickstart.md +++ b/src/building/quickstart.md @@ -1,7 +1,7 @@ # 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. +This is a quickstart guide about getting the compiler running. For more +information on the individual steps, see the other pages in this chapter. First, clone the repository: @@ -10,34 +10,38 @@ 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". -It is invoked with `./x`. +When building the compiler, we don't use `cargo` directly, instead we use a +wrapper called "x". It is invoked with `./x`. -We need to create a configuration for the build. Use `./x setup` to create a good default. +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. +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. +> 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. +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. +Now you have a toolchain called `stage1` linked to your build. You can use it to +test the compiler. ```sh rustc +stage1 testfile.rs @@ -46,19 +50,25 @@ 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 compiler change, -testing all [UI tests](../tests/ui.md) that invoke the compiler on a specific test file and check the output. +Usually, `./x test tests/ui` is what you want after a compiler change, 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. +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. +> `./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). +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). -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). +If you use VSCode, Vim, Emacs or Helix, `./x setup` will ask you if you want to +set up the editor config. For more information, check out [suggested +workflows](./suggested.md). diff --git a/src/building/suggested.md b/src/building/suggested.md index 927648104..58f36eadd 100644 --- a/src/building/suggested.md +++ b/src/building/suggested.md @@ -15,10 +15,8 @@ par. If the hook fails then run `./x test tidy --bless` and commit the changes. If you decide later that the pre-push behavior is undesirable, you can delete the `pre-push` file in `.git/hooks`. -A prebuilt git hook lives at -[`src/etc/pre-push.sh`](https://github.com/rust-lang/rust/blob/master/src/etc/pre-push.sh) -which can be copied into your `.git/hooks` folder as `pre-push` (without the -`.sh` extension!). +A prebuilt git hook lives at [`src/etc/pre-push.sh`]. It can be copied into +your `.git/hooks` folder as `pre-push` (without the `.sh` extension!). You can also install the hook as a step of running `./x setup`! @@ -43,11 +41,16 @@ If you have enough free disk space and you would like to be able to run `x` commands while rust-analyzer runs in the background, you can also add `--build-dir build-rust-analyzer` to the `overrideCommand` to avoid x locking. +Running `./x setup editor` will prompt you to create a project-local LSP config +file for one of the supported editors. You can also create the config file as a +step of running `./x setup`. + ### Visual Studio Code -Running `./x setup vscode` will prompt you to create a `.vscode/settings.json` -file which will configure Visual Studio code. The recommended `rust-analyzer` -settings live at [`src/etc/rust_analyzer_settings.json`]. +Selecting `vscode` in `./x setup editor` will prompt you to create a +`.vscode/settings.json` file which will configure Visual Studio code. The +recommended `rust-analyzer` settings live at +[`src/etc/rust_analyzer_settings.json`]. If running `./x check` on save is inconvenient, in VS Code you can use a [Build Task] instead: @@ -83,13 +86,14 @@ here](https://rust-analyzer.github.io/manual.html#nvim-lsp). 1. First install the plugin. This can be done by following the steps in the README. -2. Run `x setup`, which will have a prompt for it to create a +2. Run `./x setup editor`, and select `vscode` to create a `.vscode/settings.json` file. `neoconf` is able to read and update rust-analyzer settings automatically when the project is opened when this file is detected. -If you're running `coc.nvim`, you can use `:CocLocalConfig` to create a -`.vim/coc-settings.json`, and copy the settings from +If you're using `coc.nvim`, you can run `./x setup editor` and select `vim` to +create a `.vim/coc-settings.json`. The settings can be edited with +`:CocLocalConfig`. The recommended settings live at [`src/etc/rust_analyzer_settings.json`]. Another way is without a plugin, and creating your own logic in your @@ -111,10 +115,10 @@ Emacs provides support for rust-analyzer with project-local configuration through [Eglot](https://www.gnu.org/software/emacs/manual/html_node/eglot/). Steps for setting up Eglot with rust-analyzer can be [found here](https://rust-analyzer.github.io/manual.html#eglot). -Having set up Emacs & Eglot for Rust development in general, you can use the -configuration for rustc provided in [`src/etc/rust_analyzer_eglot.el`]( -https://github.com/rust-lang/rust/blob/master/src/etc/rust_analyzer_eglot.el). -Simply copy the provided file to `.dir-locals.el` in the project root directory. +Having set up Emacs & Eglot for Rust development in general, you can run +`./x setup editor` and select `emacs`, which will prompt you to create +`.dir-locals.el` with the recommended configuration for Eglot. +The recommended settings live at [`src/etc/rust_analyzer_eglot.el`]. For more information on project-specific Eglot configuration, consult [the manual](https://www.gnu.org/software/emacs/manual/html_node/eglot/Project_002dspecific-configuration.html). @@ -123,14 +127,13 @@ manual](https://www.gnu.org/software/emacs/manual/html_node/eglot/Project_002dsp Helix comes with built-in LSP and rust-analyzer support. It can be configured through `languages.toml`, as described [here](https://docs.helix-editor.com/languages.html). -You can use the configuration for rustc provided in -[`src/etc/rust_analyzer_helix.toml`](https://github.com/rust-lang/rust/blob/master/src/etc/rust_analyzer_helix.toml). -Simply copy the provided file to `.helix/languages.toml` in the project root -directory. +You can run `./x setup editor` and select `helix`, which will prompt you to +create `languages.toml` with the recommended configuration for Helix. The +recommended settings live at [`src/etc/rust_analyzer_helix.toml`]. ## Check, check, and check again -When doing simple refactorings, it can be useful to run `./x check` +When doing simple refactoring, it can be useful to run `./x check` continuously. If you set up `rust-analyzer` as described above, this will be done for you every time you save a file. Here you are just checking that the compiler can **build**, but often that is all you need (e.g., when renaming a @@ -356,3 +359,6 @@ Adding this to your shell's startup script (e.g. `.bashrc`) will automatically load this completion. [`src/etc/rust_analyzer_settings.json`]: https://github.com/rust-lang/rust/blob/master/src/etc/rust_analyzer_settings.json +[`src/etc/rust_analyzer_eglot.el`]: https://github.com/rust-lang/rust/blob/master/src/etc/rust_analyzer_eglot.el +[`src/etc/rust_analyzer_helix.toml`]: https://github.com/rust-lang/rust/blob/master/src/etc/rust_analyzer_helix.toml +[`src/etc/pre-push.sh`]: https://github.com/rust-lang/rust/blob/master/src/etc/pre-push.sh