From df14c010beffc9d89018806974bb07a6358bfedb Mon Sep 17 00:00:00 2001 From: David Kurilla Date: Tue, 15 Oct 2024 12:45:29 -0700 Subject: [PATCH 1/3] docs: create setup documentation --- docs/dev/setup.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 docs/dev/setup.md diff --git a/docs/dev/setup.md b/docs/dev/setup.md new file mode 100644 index 0000000000..ac8117e0f3 --- /dev/null +++ b/docs/dev/setup.md @@ -0,0 +1,63 @@ +# Setup Guide + +This guide gives a simplified opinionated setup for developers contributing to rust-analyzer. + +## Prerequisites + +Since rust-analyzer is a Rust project, you will need to install Rust. You can download and install the latest stable version of Rust [here](https://www.rust-lang.org/tools/install). + +You will also need Visual Studio Code and Visual Studio Code Insiders for this workflow. You can download and install Visual Studio Code [here](https://code.visualstudio.com/Download) and you can download and install Visual Studio Code Insiders [here](https://code.visualstudio.com/insiders/). + +You will also need to install the rust-analyzer extension for Visual Studio Code and Visual Studio Code Insiders. + +More information about Rust on Visual Studio Code can be found [here](https://code.visualstudio.com/docs/languages/rust) + +## Step-by-Step Setup + +**Step 01**: Fork the rust-analyzer repository and clone the fork to your local machine. + +**Step 02**: Open the project in Visual Studio Code. + +**Step 03**: Open a terminal and run `cargo build` to build the project. + +**Step 04**: Install the language server locally by running the following command: + +```sh +cargo xtask install --server --code-bin code-insiders --dev-rel +``` + +In the output of this command, there should be a file path provided to the installed binary on your local machine. +It should look something like the following output below + +``` +Installing +Installed package `rust-analyzer v0.0.0 ()` (executable `rust-analyzer.exe`) +``` + +In Visual Studio Code Insiders, you will want to open your User Settings (JSON) from the Command Palette. From there you should ensure that the `rust-anaylzer.server.path` key is set to the ``. This will tell Visual Studio Code Insiders to use the locally installed version that you can debug. + +The User Settings (JSON) file should contain the following: + +```json +{ + "rust-analyzer.server.path": "" +} +``` + +Now you should be able to make changes to rust-analyzer in Visual Studio Code and then view the changes in Visual Studio Code Insiders. + +## Debugging rust-analyzer +The simplist way to debug rust-analyzer is to use the `eprintln!` macro. The reason why we use `eprintln!` instead of `println!` is because the language server uses `stdout` to send messages. So instead we will debug using `stderr`. + +An example debugging statement could go into the `main_loop.rs` file which can be found at `crates/rust-analyzer/src/main_loop.rs`. Inside the `main_loop` we will add the following `eprintln!` to test debugging rust-analyzer: + +```rs +eprintln!("Hello, world!"); +``` + +Now we run `cargo build` and `sh +cargo xtask install --server --code-bin code-insiders --dev-rel` to reinstall the server. + +Now on Visual Studio Code Insiders, we should be able to open the Output tab on our terminal and switch to Rust Analyzer Language Server to see the `eprintln!` statement we just wrote. + +If you are able to see your output, you now have a complete workflow for debugging rust-analyzer. \ No newline at end of file From 9ee29f4254f74759a38814b5f13dc0a27070fc88 Mon Sep 17 00:00:00 2001 From: David Kurilla Date: Tue, 15 Oct 2024 12:49:51 -0700 Subject: [PATCH 2/3] style: fix typos --- docs/dev/setup.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/dev/setup.md b/docs/dev/setup.md index ac8117e0f3..62b8bd9a44 100644 --- a/docs/dev/setup.md +++ b/docs/dev/setup.md @@ -34,20 +34,20 @@ Installing Installed package `rust-analyzer v0.0.0 ()` (executable `rust-analyzer.exe`) ``` -In Visual Studio Code Insiders, you will want to open your User Settings (JSON) from the Command Palette. From there you should ensure that the `rust-anaylzer.server.path` key is set to the ``. This will tell Visual Studio Code Insiders to use the locally installed version that you can debug. +In Visual Studio Code Insiders, you will want to open your User Settings (JSON) from the Command Palette. From there you should ensure that the `rust-analyzer.server.path` key is set to the ``. This will tell Visual Studio Code Insiders to use the locally installed version that you can debug. The User Settings (JSON) file should contain the following: ```json { - "rust-analyzer.server.path": "" + "rust-analyzer.server.path": "" } ``` Now you should be able to make changes to rust-analyzer in Visual Studio Code and then view the changes in Visual Studio Code Insiders. ## Debugging rust-analyzer -The simplist way to debug rust-analyzer is to use the `eprintln!` macro. The reason why we use `eprintln!` instead of `println!` is because the language server uses `stdout` to send messages. So instead we will debug using `stderr`. +The simplest way to debug rust-analyzer is to use the `eprintln!` macro. The reason why we use `eprintln!` instead of `println!` is because the language server uses `stdout` to send messages. So instead we will debug using `stderr`. An example debugging statement could go into the `main_loop.rs` file which can be found at `crates/rust-analyzer/src/main_loop.rs`. Inside the `main_loop` we will add the following `eprintln!` to test debugging rust-analyzer: From 0719432903271c2432021eef451dc01b7aeb6612 Mon Sep 17 00:00:00 2001 From: David Kurilla <130074511+davidkurilla@users.noreply.github.com> Date: Tue, 22 Oct 2024 08:44:02 -0700 Subject: [PATCH 3/3] docs: remove unnecessary prerequisites setup.md --- docs/dev/setup.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/dev/setup.md b/docs/dev/setup.md index 62b8bd9a44..d8a7840d37 100644 --- a/docs/dev/setup.md +++ b/docs/dev/setup.md @@ -1,17 +1,11 @@ # Setup Guide -This guide gives a simplified opinionated setup for developers contributing to rust-analyzer. +This guide gives a simplified opinionated setup for developers contributing to rust-analyzer using Visual Studio Code to make changes and Visual Studio Code Insiders to test those changes. This guide will assume you have Visual Studio Code and Visual Studio Code Insiders installed. ## Prerequisites Since rust-analyzer is a Rust project, you will need to install Rust. You can download and install the latest stable version of Rust [here](https://www.rust-lang.org/tools/install). -You will also need Visual Studio Code and Visual Studio Code Insiders for this workflow. You can download and install Visual Studio Code [here](https://code.visualstudio.com/Download) and you can download and install Visual Studio Code Insiders [here](https://code.visualstudio.com/insiders/). - -You will also need to install the rust-analyzer extension for Visual Studio Code and Visual Studio Code Insiders. - -More information about Rust on Visual Studio Code can be found [here](https://code.visualstudio.com/docs/languages/rust) - ## Step-by-Step Setup **Step 01**: Fork the rust-analyzer repository and clone the fork to your local machine. @@ -27,7 +21,7 @@ cargo xtask install --server --code-bin code-insiders --dev-rel ``` In the output of this command, there should be a file path provided to the installed binary on your local machine. -It should look something like the following output below +It should look something like the following output below: ``` Installing @@ -60,4 +54,4 @@ cargo xtask install --server --code-bin code-insiders --dev-rel` to reinstall th Now on Visual Studio Code Insiders, we should be able to open the Output tab on our terminal and switch to Rust Analyzer Language Server to see the `eprintln!` statement we just wrote. -If you are able to see your output, you now have a complete workflow for debugging rust-analyzer. \ No newline at end of file +If you are able to see your output, you now have a complete workflow for debugging rust-analyzer.