Skip to content

Commit eff5429

Browse files
matkladmatklad
committed
Add manual
1 parent 3d089fe commit eff5429

File tree

3 files changed

+154
-1
lines changed

3 files changed

+154
-1
lines changed

‎_layouts/default.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@
3434
<img src="/assets/rust-analyzer.svg" alt="rust analyzer" id="header-logo">
3535
</a>
3636
<a class="nav-link" href="https://opencollective.com/rust-analyzer/">Sponsor</a>
37+
<a class="nav-link" href="/manual.html">Docs</a>
3738
<a class="nav-link" href="/blog">Blog</a>
3839
<a class="nav-link" href="/thisweek">Changelog</a>
3940
</div>

‎index.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ <h2>Quick Start</h2>
4141
<p>
4242
Instructions for other editors, building from source and the list of features are found in
4343

44-
<a href="https://github.com/rust-analyzer/rust-analyzer/tree/master/docs/user" class="manual">
44+
<a href="/manual.html" class="manual">
4545
<strong>the manual.</strong>
4646
</a>
4747
</p>

‎manual.adoc

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
= User Manual
2+
:toc: preamble
3+
:sectanchors:
4+
:page-layout: post
5+
6+
7+
// Master copy of this document lives in the https://github.com/rust-analyzer/rust-analyzer repository
8+
9+
At it's core, rust-analyzer is a *library* for semantic analysis of the Rust code as it changes over time.
10+
This manual focuses on a specific usage of the library -- the implementation of
11+
https://microsoft.github.io/language-server-protocol/[Language Server Protocol].
12+
LSP allows various code editors, like VS Code, Emacs or Vim, to implement semantic feature like completion or goto definition by talking to an external language server process.
13+
14+
== Installation
15+
16+
In theory, one should be able to just install the server binary and have it automatically work with any editor.
17+
We are not there yet, so some editor specific setup is required.
18+
19+
=== VS Code
20+
21+
This the best supported editor at the moment.
22+
rust-analyzer plugin for VS Code is maintained
23+
https://github.com/rust-analyzer/rust-analyzer/tree/master/editors/code[in tree].
24+
25+
You can install the latest release of the plugin from
26+
https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer[the marketplace].
27+
By default, the plugin will download the latest version of the server as well.
28+
29+
image::https://user-images.githubusercontent.com/36276403/74103174-a40df100-4b52-11ea-81f4-372c70797924.png[]
30+
31+
The server binary is stored in `~/.config/Code/User/globalStorage/matklad.rust-analyzer`.
32+
33+
Note that we only support the latest version of VS Code.
34+
35+
==== Updates
36+
37+
The extension will be updated automatically as new versions become available.
38+
The server update functionality is in progress.
39+
For the time being, the workaround is to remove the binary from `globalStorage` and to restart the extension.
40+
41+
==== Building From Source
42+
43+
Alternatively, both the server and the plugin can be installed from source:
44+
45+
[source]
46+
----
47+
$ git clone https://github.com/rust-analyzer/rust-analyzer.git && cs rust-analyzer
48+
$ cargo xtask install
49+
----
50+
51+
You'll need Cargo, nodejs and npm for this.
52+
To make VS Code use the freshly build server, add this to the settings:
53+
54+
[source,json]
55+
----
56+
{ "rust-analyzer.raLspServerPath": "ra_lsp_server" }
57+
----
58+
59+
Note that installing via `xtask install` does not work for VS Code Remote, instead you'll need to install the `.vsix` manually.
60+
61+
=== Language Server Binary
62+
63+
Other editors generally require `ra_lsp_server` binary to be in `$PATH`.
64+
You can download pre-build binary from
65+
https://github.com/rust-analyzer/rust-analyzer/releases[relases]
66+
page, or you can install it from source using the following command:
67+
68+
[source,bash]
69+
----
70+
$ cargo xtask install --server
71+
----
72+
73+
=== Emacs
74+
75+
Emacs support is maintained https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-rust.el[upstream].
76+
77+
1. Install recent version of `emacs-lsp` package by following the instructions https://github.com/emacs-lsp/lsp-mode[here].
78+
2. Set `lsp-rust-server` to `'rust-analyzer`.
79+
3. Run `lsp` in a Rust buffer.
80+
4. (Optionally) bind commands like `lsp-rust-analyzer-join-lines`, `lsp-extend-selection` and `lsp-rust-analyzer-expand-macro` to keys.
81+
82+
=== Vim
83+
84+
The are several LSP client implementations for vim:
85+
86+
==== coc-rust-analyzer
87+
88+
1. Install coc.nvim by following the instructions at
89+
https://github.com/neoclide/coc.nvim[coc.nvim]
90+
(nodejs required)
91+
2. Run `:CocInstall coc-rust-analyzer` to install
92+
https://github.com/fannheyward/coc-rust-analyzer[coc-rust-analyzer],
93+
this extension implements _most_ of the features supported in the VSCode extension:
94+
* same configurations as VSCode extension, `rust-analyzer.raLspServerPath`, `rust-analyzer.enableCargoWatchOnStartup` etc.
95+
* same commands too, `rust-analyzer.analyzerStatus`, `rust-analyzer.startCargoWatch` etc.
96+
* highlighting and inlay_hints are not implemented yet
97+
98+
==== LanguageClient-neovim
99+
100+
1. Install LanguageClient-neovim by following the instructions
101+
https://github.com/autozimu/LanguageClient-neovim[here]
102+
* The github project wiki has extra tips on configuration
103+
104+
2. Configure by adding this to your vim/neovim config file (replacing the existing rust specific line if it exists):
105+
+
106+
[source,vim]
107+
----
108+
let g:LanguageClient_serverCommands = {
109+
\ 'rust': ['ra_lsp_server'],
110+
\ }
111+
----
112+
113+
==== nvim-lsp
114+
115+
NeoVim 0.5 (not yet released) has built in language server support.
116+
For a quick start configuration of rust-analyzer, use https://github.com/neovim/nvim-lsp#rust_analyzer[neovim/nvim-lsp].
117+
Once `neovim/nvim-lsp` is installed, use `lua require'nvim_lsp'.rust_analyzer.setup({})` in your `init.vim`.
118+
119+
=== Sublime Text 3
120+
121+
Prerequisites:
122+
123+
`LSP` package.
124+
125+
Installation:
126+
127+
1. Invoke the command palette with <kbd>Ctrl+Shift+P</kbd>
128+
2. Type `LSP Settings` to open the LSP preferences editor
129+
3. Add the following LSP client definition to your settings:
130+
+
131+
[source,json]
132+
----
133+
"rust-analyzer": {
134+
"command": ["ra_lsp_server"],
135+
"languageId": "rust",
136+
"scopes": ["source.rust"],
137+
"syntaxes": [
138+
"Packages/Rust/Rust.sublime-syntax",
139+
"Packages/Rust Enhanced/RustEnhanced.sublime-syntax"
140+
],
141+
"initializationOptions": {
142+
"featureFlags": {
143+
}
144+
},
145+
}
146+
----
147+
148+
4. 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)
149+
150+
== Usage
151+
152+
See https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/features.md[features.md].

0 commit comments

Comments
 (0)