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
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).

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
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