Merge pull request #793 from rust-lang/support-rust-analyzer

Support rust-analyzer as alternate LSP engine

Author: Xanewok

CHANGELOG.md

@@ -1,5 +1,6 @@
 ### Unreleased
 
+* Support rust-analyzer as an alternate LSP server
 * Bump required VSCode version to 1.43, use language server protocol (LSP) v3.15
 
 ### 0.7.5 - 2020-05-06

README.md

@@ -14,37 +14,41 @@ Adds language support for Rust to Visual Studio Code. Supports:
 * snippets
 * build tasks
 
+Rust support is powered by a separate [language server](https://microsoft.github.io/language-server-protocol/overviews/lsp/overview/)
+- either by the official [Rust Language Server](https://github.com/rust-lang/rls) (RLS) or
+[rust-analyzer](https://github.com/rust-lang/rls), depending on the user's
+preference. If you don't have it installed, the extension will install it for
+you (with permission).
 
-Rust support is powered by the [Rust Language Server](https://github.com/rust-lang/rls)
-(RLS). If you don't have it installed, the extension will install it for you.
-
-This extension is built and maintained by the RLS team, part of the Rust
+This extension is built and maintained by the Rust
 [IDEs and editors team](https://www.rust-lang.org/en-US/team.html#Dev-tools-team).
-It is the reference client implementation for the RLS. Our focus is on providing
-a stable, high quality extension that makes best use of the RLS. We aim to
-support as many features as possible, but our priority is supporting the
-essential features as well as possible.
+Our focus is on providing
+a stable, high quality extension that makes the best use of the respective language
+server. We aim to support as many features as possible, but our priority is
+supporting the essential features as well as possible.
+
+For support, please file an
+[issue on the repo](https://github.com/rust-lang/rls-vscode/issues/new)
+or talk to us [on Discord](https://discordapp.com/invite/rust-lang).
+For RLS, there is also some [troubleshooting and debugging](https://github.com/rust-lang/rls/blob/master/debugging.md) advice.
 
-For support, please file an [issue on the repo](https://github.com/rust-lang/rls-vscode/issues/new)
-or talk to us [on Discord](https://discordapp.com/invite/rust-lang). There is also some
-[troubleshooting and debugging](https://github.com/rust-lang/rls/blob/master/debugging.md)
-advice.
+## Contribution
 
 Contributing code, tests, documentation, and bug reports is appreciated! For
-more details on building and debugging, etc., see [contributing.md](contributing.md).
+more details see [contributing.md](contributing.md).
 
 
 ## Quick start
 
-* Install [rustup](https://www.rustup.rs/) (Rust toolchain manager).
-* Install this extension from [the VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust)
+1. Install [rustup](https://www.rustup.rs/) (Rust toolchain manager).
+2. Install this extension from [the VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust)
   (or by entering `ext install rust-lang.rust` at the command palette <kbd>Ctrl</kbd>+<kbd>P</kbd>).
-* (Skip this step if you already have Rust projects that you'd like to work on.)
+3. (Skip this step if you already have Rust projects that you'd like to work on.)
   Create a new Rust project by following [these instructions](https://doc.rust-lang.org/book/ch01-03-hello-cargo.html).
-* Open a Rust project (`File > Add Folder to Workspace...`). Open the folder for the whole
-  project (i.e., the folder containing 'Cargo.toml'), not the 'src' folder.
-* You'll be prompted to install the RLS. Once installed, the RLS should start
-  building your project.
+4. Open a Rust project (`File > Add Folder to Workspace...`). Open the folder for the whole
+  project (i.e., the folder containing `Cargo.toml`, not the `src` folder).
+5. You'll be prompted to install the Rust server. Once installed, it should start
+  analyzing your project (RLS will also have to to build the project).
 
 
 ## Configuration
@@ -53,24 +57,25 @@ This extension provides options in VSCode's configuration settings. These
 include `rust.*`, which are passed directly to RLS, and the `rust-client.*`
 , which mostly deal with how to spawn it or debug it.
 You can find the settings under `File > Preferences > Settings`; they all
-have Intellisense help.
+have IntelliSense help.
 
-Some highlights:
+Examples:
 
 * `rust.show_warnings` - set to false to silence warnings in the editor.
 * `rust.all_targets` - build and index code for all targets (i.e., integration tests, examples, and benches)
 * `rust.cfg_test` - build and index test code (i.e., code with `#[cfg(test)]`/`#[test]`)
-
 * `rust-client.channel` - specifies from which toolchain the RLS should be spawned
 
+> **_TIP:_** To select the underlying language server, set `rust-client.engine` accordingly!
+
 ## Features
 
 ### Snippets
 
-Snippets are code templates which expand into common boilerplate. Intellisense
-includes snippet names as options when you type; select one by pressing 'enter'.
-You can move to the next 'hole' in the template by pressing 'tab'. We provide
-the following snippets:
+Snippets are code templates which expand into common boilerplate. IntelliSense
+includes snippet names as options when you type; select one by pressing
+<kbd>enter</kbd>. You can move to the next snippet 'hole' in the template by
+pressing <kbd>tab</kbd>. We provide the following snippets:
 
 * `for` - a for loop
 * `macro_rules` - declare a macro
@@ -102,18 +107,25 @@ to `true`. Find it under `File > Preferences > Settings`.
 ## Requirements
 
 * [Rustup](https://www.rustup.rs/),
-* A Rust toolchain (the extension will configure this for you, with
-  permission),
-* `rls`, `rust-src`, and `rust-analysis` components (the
-  extension will install these for you, with permission).
+* A Rust toolchain (the extension will configure this for you, with permission),
+* `rls`, `rust-src`, and `rust-analysis` components (the extension will install
+  these for you, with permission). Only `rust-src` is required when using
+  rust-analyzer.
 
 
 ## Implementation
 
-This extension almost exclusively uses the RLS for its feature support (syntax
-highlighting, snippets, and build tasks are provided client-side). The RLS uses
-the Rust compiler (`rustc`) to get data about Rust programs. It uses Cargo to
-manage building. Both Cargo and `rustc` are run in-process by the RLS. Formatting
-and code completion are provided by `rustfmt` and Racer, again both of these are
-run in-process by the RLS.
+Both language servers can use Cargo to get more information about Rust projects
+and both use [`rustfmt`](https://github.com/rust-lang/rustfmt/) extensively to
+format the code.
+
+[RLS](https://github.com/rust-lang/rls) uses Cargo and also the Rust compiler
+([`rustc`](https://github.com/rust-lang/rust/)) in a more direct fashion, where
+it builds the project and reuses the data computed by the compiler itself. To
+provide code completion it uses a separate tool called
+[`racer`](https://github.com/racer-rust/racer).
 
+[Rust Analyzer](https://github.com/rust-analyzer/rust-analyzer) is a separate
+compiler frontend for the Rust language that doesn't use the Rust compiler
+([`rustc`](https://github.com/rust-lang/rust/)) directly but rather performs its
+own analysis that's tailor-fitted to the editor/IDE use case.

package-lock.json

@@ -50,13 +50,15 @@
         "installDevExtension": "npm install && ./node_modules/.bin/vsce package -o ./out/rls-vscode-dev.vsix && code --install-extension ./out/rls-vscode-dev.vsix"
     },
     "dependencies": {
+        "node-fetch": "^2.6.0",
         "vscode-languageclient": "^6.0.0"
     },
     "devDependencies": {
         "@types/chai": "^4.2.11",
         "@types/glob": "^7.1.1",
         "@types/mocha": "^5.2.6",
         "@types/node": "^12.8.1",
+        "@types/node-fetch": "^2.5.7",
         "@types/vscode": "^1.43.0",
         "chai": "^4.2.0",
         "glob": "^7.1.4",
@@ -87,26 +89,26 @@
         "commands": [
             {
                 "command": "rls.update",
-                "title": "Update the RLS",
-                "description": "Use Rustup to update Rust, the RLS, and required data",
+                "title": "Update the current Rust toolchain",
+                "description": "Use Rustup to the current Rust toolchain, along with its components",
                 "category": "Rust"
             },
             {
                 "command": "rls.restart",
-                "title": "Restart the RLS",
+                "title": "Restart the Rust server",
                 "description": "Sometimes, it's just best to try turning it off and on again",
                 "category": "Rust"
             },
             {
                 "command": "rls.start",
-                "title": "Start the RLS",
-                "description": "Start the RLS (when rust-client.autoStartRls is false or when manually stopped)",
+                "title": "Start the Rust server",
+                "description": "Start the Rust server (when rust-client.autoStartRls is false or when manually stopped)",
                 "category": "Rust"
             },
             {
                 "command": "rls.stop",
-                "title": "Stop the RLS",
-                "description": "Stop the RLS for a workspace until manually started again",
+                "title": "Stop the Rust server",
+                "description": "Stop the Rust server for a workspace until manually started again",
                 "category": "Rust"
             }
         ],
@@ -160,6 +162,20 @@
             "type": "object",
             "title": "Rust configuration",
             "properties": {
+                "rust-client.engine": {
+                    "type": "string",
+                    "enum": [
+                        "rls",
+                        "rust-analyzer"
+                    ],
+                    "enumDescriptions": [
+                        "Use the Rust Language Server (RLS)",
+                        "Use the rust-analyzer language server (NOTE: not fully supported yet)"
+                    ],
+                    "default": "rls",
+                    "description": "The underlying LSP server used to provide IDE support for Rust projects.",
+                    "scope": "window"
+                },
                 "rust-client.logToFile": {
                     "type": "boolean",
                     "default": false,
@@ -448,6 +464,22 @@
                     "default": true,
                     "description": "Show additional context in hover tooltips when available. This is often the type local variable declaration.",
                     "scope": "resource"
+                },
+                "rust.rust-analyzer": {
+                    "type": "object",
+                    "default": {},
+                    "description": "Settings passed down to rust-analyzer server",
+                    "scope": "resource"
+                },
+                "rust.rust-analyzer.releaseTag": {
+                    "type": "string",
+                    "default": "nightly",
+                    "description": "Which binary release to download and use"
+                },
+                "rust.rust-analyzer.path": {
+                    "type": ["string", "null"],
+                    "default": null,
+                    "description": "When specified, uses the rust-analyzer binary at a given path"
                 }
             }
         }