mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge #3071

Browse Source 
3071: Freshen docs for prebuilt binaries and raLspServer setting r=matklad a=Veetaha

Better documented breaking changes as per an incident in #2988
Follow up for #3053 


Co-authored-by: Veetaha <gerzoh1@gmail.com>
This commit is contained in:
bors[bot] 2020-02-09 20:21:47 +00:00 committed by GitHub
commit 2eb1c34f85
2 changed files with 65 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
docs/dev/README.md
View File

@ -74,7 +74,7 @@ relevant test and execute it (VS Code includes an action for running a single
test). test).
However, launching a VS Code instance with locally build language server is However, launching a VS Code instance with locally build language server is
possible. There's "Run Extension (Dev Server)" launch configuration for this. possible. There's **"Run Extension (Dev Server)"** launch configuration for this.
In general, I use one of the following workflows for fixing bugs and In general, I use one of the following workflows for fixing bugs and
implementing features. implementing features.
@ -88,7 +88,14 @@ Code to sanity check that the thing works as I expect.
If the problem concerns only the VS Code extension, I use **Run Extension** If the problem concerns only the VS Code extension, I use **Run Extension**
launch configuration from `launch.json`. Notably, this uses the usual launch configuration from `launch.json`. Notably, this uses the usual
`ra_lsp_server` binary from `PATH`. After I am done with the fix, I use `cargo `ra_lsp_server` binary from `PATH`. For this it is important to have the following
in `setting.json` file:
```json
{
"rust-analyzer.raLspServerPath": "ra_lsp_server"
}
```
After I am done with the fix, I use `cargo
xtask install --client-code` to try the new extension for real. xtask install --client-code` to try the new extension for real.
If I need to fix something in the `ra_lsp_server` crate, I feel sad because it's If I need to fix something in the `ra_lsp_server` crate, I feel sad because it's

82
docs/user/README.md
View File

@ -1,16 +1,26 @@
[github-releases]: https://github.com/rust-analyzer/rust-analyzer/releases
The main interface to rust-analyzer is the The main interface to rust-analyzer is the
[LSP](https://microsoft.github.io/language-server-protocol/) implementation. To [LSP](https://microsoft.github.io/language-server-protocol/) implementation. To
install lsp server, clone the repository and then run `cargo xtask install install lsp server, you have three options:
--server` (which is shorthand for `cargo install --path
./crates/ra_lsp_server`). This will produce a binary named `ra_lsp_server` which * **Preferred and default:** install the plugin/extension for your IDE and it will ask your permission to automatically download the latest lsp server for you from [GitHub releases][github-releases]. (See docs to find out whether this is implemented for your editor below).
you should be able to use it with any LSP-compatible editor. We use custom * Manually download prebuilt binaries from [GitHub releases][github-releases]
extensions to LSP, so special client-side support is required to take full * `ra_lsp_server-linux` for Linux
* `ra_lsp_server-mac` for Mac
* `ra_lsp_server-windows.exe` for Windows
* Clone the repository and build from sources
```bash
$ git clone git@github.com:rust-analyzer/rust-analyzer && cd rust-analyzer
$ cargo xtask install --server # or cargo install --path ./crates/ra_lsp_server
```
This way you will get a binary named `ra_lsp_server` (with os suffix for prebuilt binaries)
which you should be able to use with any LSP-compatible editor.
We make use of custom extensions to LSP, so special client-side support is required to take full
advantage of rust-analyzer. This repository contains support code for VS Code. advantage of rust-analyzer. This repository contains support code for VS Code.
```
$ git clone git@github.com:rust-analyzer/rust-analyzer && cd rust-analyzer
$ cargo xtask install --server
```
Rust Analyzer needs sources of rust standard library to work, so Rust Analyzer needs sources of rust standard library to work, so
you might also need to execute you might also need to execute
@ -22,30 +32,38 @@ See [./features.md](./features.md) document for a list of features that are avai
## VS Code ## VS Code
Prerequisites: ### Prerequisites
In order to build the VS Code plugin, you need to have node.js and npm with You will need the most recent version of VS Code: we don't try to
a minimum version of 10 installed. Please refer to
[node.js and npm documentation](https://nodejs.org) for installation instructions.
You will also need the most recent version of VS Code: we don't try to
maintain compatibility with older versions yet. maintain compatibility with older versions yet.
In order to build the VS Code plugin from sources, you need to have node.js and npm with
a minimum version of 12 installed. Please refer to
[node.js and npm documentation](https://nodejs.org) for installation instructions.
### Installation from prebuilt binaries ### Installation from prebuilt binaries
We ship prebuilt binaries for Linux, Mac and Windows via We ship prebuilt binaries for Linux, Mac and Windows via
[GitHub releases](https://github.com/rust-analyzer/rust-analyzer/releases). [GitHub releases][github-releases].
In order to use them you need to install the client VSCode extension. In order to use them you need to install the client VSCode extension.
Publishing to VSCode marketplace is currently WIP. Thus, you need to clone the repository and install **only** the client extension via Publishing to VS Code marketplace is currently WIP. Thus, you need to manually download
``` `rust-analyzer-0.1.0.vsix` file from latest [GitHub release][github-releases].
$ git clone https://github.com/rust-analyzer/rust-analyzer.git --depth 1
$ cd rust-analyzer
$ cargo xtask install --client-code
```
Then open VSCode (or reload the window if it was already running), open some Rust project and you should
see an info message pop-up.
After you downloaded the `.vsix` file you can install it from the terminal
```
$ code --install-extension rust-analyzer-0.1.0.vsix
```
Or open VS Code, press <kbd>Ctrl+Shift+P</kbd>, and search for the following command:
<img width="500px" alt="Install from VSIX command" src="https://user-images.githubusercontent.com/36276403/74108225-c0c11d80-4b80-11ea-9b2a-0a43f09e29af.png">
Press <kbd>Enter</kbd> and go to `rust-analyzer-0.1.0.vsix` file through the file explorer.
Then open some Rust project and you should
see an info message pop-up.
<img height="140px" src="https://user-images.githubusercontent.com/36276403/74103174-a40df100-4b52-11ea-81f4-372c70797924.png" alt="Download now message"/> <img height="140px" src="https://user-images.githubusercontent.com/36276403/74103174-a40df100-4b52-11ea-81f4-372c70797924.png" alt="Download now message"/>
@ -57,7 +75,7 @@ For updates you need to remove installed binary
rm -rf ${HOME}/.config/Code/User/globalStorage/matklad.rust-analyzer rm -rf ${HOME}/.config/Code/User/globalStorage/matklad.rust-analyzer
``` ```
`"Donwload latest language server"` command for VSCode and automatic updates detection is currently WIP. `"Download latest language server"` command for VSCode and automatic updates detection is currently WIP.
### Installation from sources ### Installation from sources
@ -71,6 +89,16 @@ $ cd rust-analyzer
$ cargo xtask install $ cargo xtask install
``` ```
After that you need to amend your `settings.json` file to explicitly specify the
path to `ra_lsp_server` that you've just built.
```json
{
"rust-analyzer.raLspServerPath": "ra_lsp_server"
}
```
This should work on all platforms, otherwise if installed `ra_lsp_server` is not available through your `$PATH` then see how to configure it [here](#setting-up-the-PATH-variable).
The automatic installation is expected to *just work* for common cases, if it The automatic installation is expected to *just work* for common cases, if it
doesn't, report bugs! doesn't, report bugs!
@ -127,7 +155,7 @@ host.
As an example, [Pale Fire](https://github.com/matklad/pale-fire/) color scheme tweaks rust colors. As an example, [Pale Fire](https://github.com/matklad/pale-fire/) color scheme tweaks rust colors.
* `rust-analyzer.enableEnhancedTyping`: by default, rust-analyzer intercepts the * `rust-analyzer.enableEnhancedTyping`: by default, rust-analyzer intercepts the
`Enter` key to make it easier to continue comments. Note that it may conflict with VIM emulation plugin. `Enter` key to make it easier to continue comments. Note that it may conflict with VIM emulation plugin.
* `rust-analyzer.raLspServerPath`: path to `ra_lsp_server` executable * `rust-analyzer.raLspServerPath`: path to `ra_lsp_server` executable, when absent or `null` defaults to prebuilt binary path
* `rust-analyzer.enableCargoWatchOnStartup`: prompt to install & enable `cargo * `rust-analyzer.enableCargoWatchOnStartup`: prompt to install & enable `cargo
watch` for live error highlighting (note, this **does not** use rust-analyzer) watch` for live error highlighting (note, this **does not** use rust-analyzer)
* `rust-analyzer.excludeGlobs`: a list of glob-patterns for exclusion (see globset [docs](https://docs.rs/globset) for syntax). * `rust-analyzer.excludeGlobs`: a list of glob-patterns for exclusion (see globset [docs](https://docs.rs/globset) for syntax).
@ -232,6 +260,8 @@ Installation:
* You can now invoke the command palette and type LSP enable to locally/globally enable the rust-analyzer LSP (type LSP enable, then choose either locally or globally, then select rust-analyzer) * You can now invoke the command palette and type LSP enable to locally/globally enable the rust-analyzer LSP (type LSP enable, then choose either locally or globally, then select rust-analyzer)
<!-- Update links to this header when changing it! -->
### Setting up the `PATH` variable ### Setting up the `PATH` variable
On Unix systems, `rustup` adds `~/.cargo/bin` to `PATH` by modifying the shell's On Unix systems, `rustup` adds `~/.cargo/bin` to `PATH` by modifying the shell's