mirror
/
rustc-dev-guide
mirror of https://github.com/rust-lang/rustc-dev-guide.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

building: Update instructions for ./x setup editor

This commit is contained in:
Kajetan Puchalski 2024-10-05 22:09:26 +01:00 committed by Jakub Beránek
parent 9bb0da343a
commit ab71898fc7
2 changed files with 56 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
src/building/quickstart.md
View File

@ -1,7 +1,7 @@
# Quickstart # Quickstart
This is a quickstart guide about getting the compiler running. For more information in the individual steps, This is a quickstart guide about getting the compiler running. For more
see the other pages in this chapter. information on the individual steps, see the other pages in this chapter.
First, clone the repository: First, clone the repository:
@ -10,34 +10,38 @@ git clone https://github.com/rust-lang/rust.git
cd rust cd rust
``` ```
When building the compiler, we don't use `cargo` directly, instead we use a wrapper called "x". When building the compiler, we don't use `cargo` directly, instead we use a
It is invoked with `./x`. 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 ```sh
./x setup ./x setup
``` ```
Then, we can build the compiler. Use `./x build` to build the compiler, standard library and a few tools. Then, we can build the compiler. Use `./x build` to build the compiler, standard
You can also `./x check` to just check it. library and a few tools. You can also `./x check` to just check it. All these
All these commands can take specific components/paths as arguments, for example `./x check compiler` to just check the compiler. commands can take specific components/paths as arguments, for example `./x check
compiler` to just check the compiler.
```sh ```sh
./x build ./x build
``` ```
> When doing a change to the compiler that does not affect the way it compiles the standard library > When doing a change to the compiler that does not affect the way it compiles
(so for example, a change to an error message), use `--keep-stage-std 1` to avoid recompiling it. 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. After building the compiler and standard library, you now have a working
You can use it with rustup by linking it. compiler toolchain. You can use it with rustup by linking it.
```sh ```sh
rustup toolchain link stage1 build/host/stage1 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 ```sh
rustc +stage1 testfile.rs 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`. 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. `./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, Usually, `./x test tests/ui` is what you want after a compiler change, testing
testing all [UI tests](../tests/ui.md) that invoke the compiler on a specific test file and check the output. all [UI tests](../tests/ui.md) that invoke the compiler on a specific test file
and check the output.
```sh ```sh
./x test tests/ui ./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, Congrats, you are now ready to make a change to the compiler! If you have more
[the full chapter](./how-to-build-and-run.md) might contain the answers, and if it doesn't, questions, [the full chapter](./how-to-build-and-run.md) might contain the
feel free to ask for help on [Zulip](https://rust-lang.zulipchat.com/#narrow/stream/182449-t-compiler.2Fhelp). 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).

44
src/building/suggested.md
View File

@ -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 If you decide later that the pre-push behavior is undesirable, you can delete
the `pre-push` file in `.git/hooks`. the `pre-push` file in `.git/hooks`.
A prebuilt git hook lives at A prebuilt git hook lives at [`src/etc/pre-push.sh`]. It can be copied into
[`src/etc/pre-push.sh`](https://github.com/rust-lang/rust/blob/master/src/etc/pre-push.sh) your `.git/hooks` folder as `pre-push` (without the `.sh` extension!).
which 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`! 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 commands while rust-analyzer runs in the background, you can also add
`--build-dir build-rust-analyzer` to the `overrideCommand` to avoid x locking. `--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 ### Visual Studio Code
Running `./x setup vscode` will prompt you to create a `.vscode/settings.json` Selecting `vscode` in `./x setup editor` will prompt you to create a
file which will configure Visual Studio code. The recommended `rust-analyzer` `.vscode/settings.json` file which will configure Visual Studio code. The
settings live at [`src/etc/rust_analyzer_settings.json`]. 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 If running `./x check` on save is inconvenient, in VS Code you can use a [Build
Task] instead: 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 1. First install the plugin. This can be done by following the steps in the
README. 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 `.vscode/settings.json` file. `neoconf` is able to read and update
rust-analyzer settings automatically when the project is opened when this rust-analyzer settings automatically when the project is opened when this
file is detected. file is detected.
If you're running `coc.nvim`, you can use `:CocLocalConfig` to create a If you're using `coc.nvim`, you can run `./x setup editor` and select `vim` to
`.vim/coc-settings.json`, and copy the settings from create a `.vim/coc-settings.json`. The settings can be edited with
`:CocLocalConfig`. The recommended settings live at
[`src/etc/rust_analyzer_settings.json`]. [`src/etc/rust_analyzer_settings.json`].
Another way is without a plugin, and creating your own logic in your 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/). through [Eglot](https://www.gnu.org/software/emacs/manual/html_node/eglot/).
Steps for setting up Eglot with rust-analyzer can be [found Steps for setting up Eglot with rust-analyzer can be [found
here](https://rust-analyzer.github.io/manual.html#eglot). here](https://rust-analyzer.github.io/manual.html#eglot).
Having set up Emacs & Eglot for Rust development in general, you can use the Having set up Emacs & Eglot for Rust development in general, you can run
configuration for rustc provided in [`src/etc/rust_analyzer_eglot.el`]( `./x setup editor` and select `emacs`, which will prompt you to create
https://github.com/rust-lang/rust/blob/master/src/etc/rust_analyzer_eglot.el). `.dir-locals.el` with the recommended configuration for Eglot.
Simply copy the provided file to `.dir-locals.el` in the project root directory. The recommended settings live at [`src/etc/rust_analyzer_eglot.el`].
For more information on project-specific Eglot configuration, consult [the 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). 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. Helix comes with built-in LSP and rust-analyzer support.
It can be configured through `languages.toml`, as described It can be configured through `languages.toml`, as described
[here](https://docs.helix-editor.com/languages.html). [here](https://docs.helix-editor.com/languages.html).
You can use the configuration for rustc provided in You can run `./x setup editor` and select `helix`, which will prompt you to
[`src/etc/rust_analyzer_helix.toml`](https://github.com/rust-lang/rust/blob/master/src/etc/rust_analyzer_helix.toml). create `languages.toml` with the recommended configuration for Helix. The
Simply copy the provided file to `.helix/languages.toml` in the project root recommended settings live at [`src/etc/rust_analyzer_helix.toml`].
directory.
## Check, check, and check again ## 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 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 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 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. 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_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