From e18661f62b884ba970f8b3267400bf4320c7b118 Mon Sep 17 00:00:00 2001 From: Veetaha Date: Sun, 9 Feb 2020 20:19:23 +0200 Subject: docs: Freshen docs for prebuilt binaries and raLspServer setting --- docs/dev/README.md | 11 +++++++++-- docs/user/README.md | 17 ++++++++++++++--- 2 files changed, 23 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/dev/README.md b/docs/dev/README.md index 732e4bdd3..991deaf90 100644 --- a/docs/dev/README.md +++ b/docs/dev/README.md @@ -74,7 +74,7 @@ relevant test and execute it (VS Code includes an action for running a single test). 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 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** 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. If I need to fix something in the `ra_lsp_server` crate, I feel sad because it's diff --git a/docs/user/README.md b/docs/user/README.md index 3da30a193..1e7d516c5 100644 --- a/docs/user/README.md +++ b/docs/user/README.md @@ -57,7 +57,7 @@ For updates you need to remove installed binary 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 @@ -71,6 +71,16 @@ $ cd rust-analyzer $ 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 doesn't, report bugs! @@ -127,7 +137,7 @@ host. 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 `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 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). @@ -232,7 +242,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) -### Setting up the `PATH` variable + +### Setting up the `PATH` variable On Unix systems, `rustup` adds `~/.cargo/bin` to `PATH` by modifying the shell's startup file. Depending on your configuration, your Desktop Environment might not -- cgit v1.2.3 From 3ebbeb46d42dd45f7769fe3e62f4ecf6a06d8409 Mon Sep 17 00:00:00 2001 From: Veetaha Date: Sun, 9 Feb 2020 21:25:24 +0200 Subject: docs: more documentation on prebuilt binaries all-editors-wise --- docs/user/README.md | 62 ++++++++++++++++++++++++++++++++++------------------- 1 file changed, 40 insertions(+), 22 deletions(-) (limited to 'docs') diff --git a/docs/user/README.md b/docs/user/README.md index 1e7d516c5..3f69a1710 100644 --- a/docs/user/README.md +++ b/docs/user/README.md @@ -1,16 +1,26 @@ +[github-releases]: https://github.com/rust-analyzer/rust-analyzer/releases + The main interface to rust-analyzer is the [LSP](https://microsoft.github.io/language-server-protocol/) implementation. To -install lsp server, clone the repository and then run `cargo xtask install ---server` (which is shorthand for `cargo install --path -./crates/ra_lsp_server`). This will produce a binary named `ra_lsp_server` which -you should be able to use it with any LSP-compatible editor. We use 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. - -``` +install lsp server, you have three options: + +* **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). +* Manually download prebuilt binaries from [GitHub releases][github-releases] + * `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 +$ 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. + Rust Analyzer needs sources of rust standard library to work, so 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 -Prerequisites: +### Prerequisites -In order to build the VS Code plugin, you need to have node.js and npm with -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 +You will need the most recent version of VS Code: we don't try to 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 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. -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]. + +After you downloaded the `.vsix` file you can install it from the terminal + ``` -$ git clone https://github.com/rust-analyzer/rust-analyzer.git --depth 1 -$ cd rust-analyzer -$ cargo xtask install --client-code +$ code --install-extension rust-analyzer-0.1.0.vsix ``` -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. +Or open VS Code, press Ctrl+Shift+P, and search for the following command: + +Install from VSIX command + +Press Enter 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. Download now message -- cgit v1.2.3 From 843d00ec9d20bab9993f45d852a4f2c70a4b10d8 Mon Sep 17 00:00:00 2001 From: Veetaha Date: Sun, 9 Feb 2020 21:40:39 +0200 Subject: docs: quick fix inner link in docs --- docs/user/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/README.md b/docs/user/README.md index 3f69a1710..6afe51e8b 100644 --- a/docs/user/README.md +++ b/docs/user/README.md @@ -261,7 +261,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) -### Setting up the `PATH` variable + +### Setting up the `PATH` variable On Unix systems, `rustup` adds `~/.cargo/bin` to `PATH` by modifying the shell's startup file. Depending on your configuration, your Desktop Environment might not -- cgit v1.2.3