diff options
author | bors[bot] <bors[bot]@users.noreply.github.com> | 2019-03-20 14:48:25 +0000 |
---|---|---|
committer | bors[bot] <bors[bot]@users.noreply.github.com> | 2019-03-20 14:48:25 +0000 |
commit | 90ff3ba64133c1bcae9d49709c4dd704ae59b1ee (patch) | |
tree | 7bc6798bb03af8148effab8f6a8a304d05d171bd | |
parent | 69ee5c9c5ef212f7911028c9ddf581559e6565c3 (diff) | |
parent | 290237d2eb472522191721397d0c4db905cdc565 (diff) |
Merge #1000
1000: Clean up some documentation debt r=Xanewok a=matklad
Co-authored-by: Aleksey Kladov <[email protected]>
Co-authored-by: bjorn3 <[email protected]>
-rw-r--r-- | CONTRIBUTING.md | 18 | ||||
-rw-r--r-- | README.md | 116 | ||||
-rw-r--r-- | ROADMAP.md | 77 | ||||
-rw-r--r-- | docs/dev/README.md | 124 | ||||
-rw-r--r-- | docs/dev/architecture.md (renamed from ARCHITECTURE.md) | 63 | ||||
-rw-r--r-- | docs/dev/debugging.md (renamed from DEBUGGING.md) | 0 | ||||
-rw-r--r-- | docs/dev/guide.md (renamed from guide.md) | 0 | ||||
-rw-r--r-- | docs/dev/lsp-features.md | 74 | ||||
-rw-r--r-- | docs/user/README.md | 77 | ||||
-rw-r--r-- | docs/user/features.md | 359 | ||||
-rw-r--r-- | editors/README.md | 241 |
11 files changed, 687 insertions, 462 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index a2efc7afa..000000000 --- a/CONTRIBUTING.md +++ /dev/null | |||
@@ -1,18 +0,0 @@ | |||
1 | The project is in its early stages: contributions are welcome and would be | ||
2 | **very** helpful, but the project is not _yet_ optimized for contribution. | ||
3 | Moreover, it is doubly experimental, so there's no guarantee that any work here | ||
4 | would reach production. | ||
5 | |||
6 | To get an idea of how rust-analyzer works, take a look at the [ARCHITECTURE.md](./ARCHITECTURE.md) | ||
7 | document. | ||
8 | |||
9 | Useful labels on the issue tracker: | ||
10 | * [E-mentor](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-mentor) | ||
11 | issues have links to the code in question and tests, | ||
12 | * [E-easy](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy), | ||
13 | [E-medium](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-medium), | ||
14 | [E-hard](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-hard), | ||
15 | labels are *estimates* for how hard would be to write a fix. | ||
16 | |||
17 | There's no formal PR check list: everything that passes CI (we use [bors](https://bors.tech/)) is valid, | ||
18 | but it's a good idea to write nice commit messages, test code thoroughly, maintain consistent style, etc. | ||
@@ -13,32 +13,37 @@ Work on the Rust Analyzer is sponsored by | |||
13 | 13 | ||
14 | [![Ferrous Systems](https://ferrous-systems.com/images/ferrous-logo-text.svg)](https://ferrous-systems.com/) | 14 | [![Ferrous Systems](https://ferrous-systems.com/images/ferrous-logo-text.svg)](https://ferrous-systems.com/) |
15 | 15 | ||
16 | ## Quick Start | 16 | ## Language Server Quick Start |
17 | 17 | ||
18 | Rust analyzer builds on Rust >= 1.31.0 and uses the 2018 edition. | 18 | Rust Analyzer is a work-in-progress, so you'll have to build it from source, and |
19 | you might encounter critical bugs. That said, it is complete enough to provide a | ||
20 | useful IDE experience and some people use it as a daily driver. | ||
19 | 21 | ||
20 | ``` | 22 | To build rust-analyzer, you need: |
21 | # run tests | ||
22 | $ cargo test | ||
23 | 23 | ||
24 | # show syntax tree of a Rust file | 24 | * latest stable rust for language server itself |
25 | $ cargo run --package ra_cli parse < crates/ra_syntax/src/lib.rs | 25 | * latest stable npm and VS Code for VS Code extension (`code` should be in path) |
26 | 26 | ||
27 | # show symbols of a Rust file | 27 | For setup for other editors, see [./docs/user](./docs/user). |
28 | $ cargo run --package ra_cli symbols < crates/ra_syntax/src/lib.rs | ||
29 | 28 | ||
30 | # install the language server | ||
31 | $ cargo install-lsp | ||
32 | or | ||
33 | $ cargo install --path crates/ra_lsp_server | ||
34 | ``` | 29 | ``` |
30 | # clone the repo | ||
31 | $ git clone https://github.com/rust-analyzer/rust-analyzer && cd rust-analyzer | ||
32 | |||
33 | # install both the language server and VS Code extension | ||
34 | $ cargo install-code | ||
35 | 35 | ||
36 | See [these instructions](./editors/README.md) for VS Code setup and the list of | 36 | # alternatively, install only the server. Binary name is `ra_lsp_server`. |
37 | features (some of which are VS Code specific). | 37 | $ cargo install-lsp |
38 | ``` | ||
39 | ## Documentation | ||
38 | 40 | ||
39 | ## Debugging | 41 | If you want to **contribute** to rust-analyzer or just curious about how things work |
42 | under the hood, check the [./docs/dev](./docs/dev) folder. | ||
40 | 43 | ||
41 | See [these instructions](./DEBUGGING.md) on how to debug the vscode extension and the lsp server. | 44 | If you want to **use** rust-analyzer's language server with your editor of |
45 | choice, check [./docs/user](./docs/user) folder. It also contains some tips & tricks to help | ||
46 | you be more productive when using rust-analyzer. | ||
42 | 47 | ||
43 | ## Getting in touch | 48 | ## Getting in touch |
44 | 49 | ||
@@ -46,83 +51,6 @@ We are on the rust-lang Zulip! | |||
46 | 51 | ||
47 | https://rust-lang.zulipchat.com/#narrow/stream/185405-t-compiler.2Frls-2.2E0 | 52 | https://rust-lang.zulipchat.com/#narrow/stream/185405-t-compiler.2Frls-2.2E0 |
48 | 53 | ||
49 | ## Contributing | ||
50 | |||
51 | See [CONTRIBUTING.md](./CONTRIBUTING.md) and [ARCHITECTURE.md](./ARCHITECTURE.md) | ||
52 | |||
53 | ## Supported LSP features | ||
54 | |||
55 | ### General | ||
56 | - [x] [initialize](https://microsoft.github.io/language-server-protocol/specification#initialize) | ||
57 | - [x] [initialized](https://microsoft.github.io/language-server-protocol/specification#initialized) | ||
58 | - [x] [shutdown](https://microsoft.github.io/language-server-protocol/specification#shutdown) | ||
59 | - [ ] [exit](https://microsoft.github.io/language-server-protocol/specification#exit) | ||
60 | - [x] [$/cancelRequest](https://microsoft.github.io/language-server-protocol/specification#cancelRequest) | ||
61 | |||
62 | ### Workspace | ||
63 | - [ ] [workspace/workspaceFolders](https://microsoft.github.io/language-server-protocol/specification#workspace_workspaceFolders) | ||
64 | - [ ] [workspace/didChangeWorkspaceFolders](https://microsoft.github.io/language-server-protocol/specification#workspace_didChangeWorkspaceFolders) | ||
65 | - [x] [workspace/didChangeConfiguration](https://microsoft.github.io/language-server-protocol/specification#workspace_didChangeConfiguration) | ||
66 | - [ ] [workspace/configuration](https://microsoft.github.io/language-server-protocol/specification#workspace_configuration) | ||
67 | - [x] [workspace/didChangeWatchedFiles](https://microsoft.github.io/language-server-protocol/specification#workspace_didChangeWatchedFiles) | ||
68 | - [x] [workspace/symbol](https://microsoft.github.io/language-server-protocol/specification#workspace_symbol) | ||
69 | - [x] [workspace/executeCommand](https://microsoft.github.io/language-server-protocol/specification#workspace_executeCommand) | ||
70 | - `apply_code_action` | ||
71 | - [ ] [workspace/applyEdit](https://microsoft.github.io/language-server-protocol/specification#workspace_applyEdit) | ||
72 | |||
73 | ### Text Synchronization | ||
74 | - [x] [textDocument/didOpen](https://microsoft.github.io/language-server-protocol/specification#textDocument_didOpen) | ||
75 | - [x] [textDocument/didChange](https://microsoft.github.io/language-server-protocol/specification#textDocument_didChange) | ||
76 | - [ ] [textDocument/willSave](https://microsoft.github.io/language-server-protocol/specification#textDocument_willSave) | ||
77 | - [ ] [textDocument/willSaveWaitUntil](https://microsoft.github.io/language-server-protocol/specification#textDocument_willSaveWaitUntil) | ||
78 | - [x] [textDocument/didSave](https://microsoft.github.io/language-server-protocol/specification#textDocument_didSave) | ||
79 | - [x] [textDocument/didClose](https://microsoft.github.io/language-server-protocol/specification#textDocument_didClose) | ||
80 | |||
81 | ### Diagnostics | ||
82 | - [x] [textDocument/publishDiagnostics](https://microsoft.github.io/language-server-protocol/specification#textDocument_publishDiagnostics) | ||
83 | |||
84 | ### Lanuguage Features | ||
85 | - [x] [textDocument/completion](https://microsoft.github.io/language-server-protocol/specification#textDocument_completion) | ||
86 | - open close: false | ||
87 | - change: Full | ||
88 | - will save: false | ||
89 | - will save wait until: false | ||
90 | - save: false | ||
91 | - [x] [completionItem/resolve](https://microsoft.github.io/language-server-protocol/specification#completionItem_resolve) | ||
92 | - resolve provider: none | ||
93 | - trigger characters: `:`, `.` | ||
94 | - [x] [textDocument/hover](https://microsoft.github.io/language-server-protocol/specification#textDocument_hover) | ||
95 | - [x] [textDocument/signatureHelp](https://microsoft.github.io/language-server-protocol/specification#textDocument_signatureHelp) | ||
96 | - trigger characters: `(`, `,`, `)` | ||
97 | - [ ] [textDocument/declaration](https://microsoft.github.io/language-server-protocol/specification#textDocument_declaration) | ||
98 | - [x] [textDocument/definition](https://microsoft.github.io/language-server-protocol/specification#textDocument_definition) | ||
99 | - [ ] [textDocument/typeDefinition](https://microsoft.github.io/language-server-protocol/specification#textDocument_typeDefinition) | ||
100 | - [x] [textDocument/implementation](https://microsoft.github.io/language-server-protocol/specification#textDocument_implementation) | ||
101 | - [x] [textDocument/references](https://microsoft.github.io/language-server-protocol/specification#textDocument_references) | ||
102 | - [x] [textDocument/documentHighlight](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentHighlight) | ||
103 | - [x] [textDocument/documentSymbol](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentSymbol) | ||
104 | - [x] [textDocument/codeAction](https://microsoft.github.io/language-server-protocol/specification#textDocument_codeAction) | ||
105 | - rust-analyzer.syntaxTree | ||
106 | - rust-analyzer.extendSelection | ||
107 | - rust-analyzer.matchingBrace | ||
108 | - rust-analyzer.parentModule | ||
109 | - rust-analyzer.joinLines | ||
110 | - rust-analyzer.run | ||
111 | - rust-analyzer.analyzerStatus | ||
112 | - [x] [textDocument/codeLens](https://microsoft.github.io/language-server-protocol/specification#textDocument_codeLens) | ||
113 | - [ ] [textDocument/documentLink](https://microsoft.github.io/language-server-protocol/specification#codeLens_resolve) | ||
114 | - [ ] [documentLink/resolve](https://microsoft.github.io/language-server-protocol/specification#documentLink_resolve) | ||
115 | - [ ] [textDocument/documentColor](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentColor) | ||
116 | - [ ] [textDocument/colorPresentation](https://microsoft.github.io/language-server-protocol/specification#textDocument_colorPresentation) | ||
117 | - [x] [textDocument/formatting](https://microsoft.github.io/language-server-protocol/specification#textDocument_formatting) | ||
118 | - [ ] [textDocument/rangeFormatting](https://microsoft.github.io/language-server-protocol/specification#textDocument_rangeFormatting) | ||
119 | - [x] [textDocument/onTypeFormatting](https://microsoft.github.io/language-server-protocol/specification#textDocument_onTypeFormatting) | ||
120 | - first trigger character: `=` | ||
121 | - more trigger character `.` | ||
122 | - [x] [textDocument/rename](https://microsoft.github.io/language-server-protocol/specification#textDocument_rename) | ||
123 | - [x] [textDocument/prepareRename](https://microsoft.github.io/language-server-protocol/specification#textDocument_prepareRename) | ||
124 | - [x] [textDocument/foldingRange](https://microsoft.github.io/language-server-protocol/specification#textDocument_foldingRange) | ||
125 | |||
126 | ## License | 54 | ## License |
127 | 55 | ||
128 | Rust analyzer is primarily distributed under the terms of both the MIT | 56 | Rust analyzer is primarily distributed under the terms of both the MIT |
diff --git a/ROADMAP.md b/ROADMAP.md deleted file mode 100644 index 3856ebc5b..000000000 --- a/ROADMAP.md +++ /dev/null | |||
@@ -1,77 +0,0 @@ | |||
1 | # Rust Analyzer Roadmap 01 | ||
2 | |||
3 | Written on 2018-11-06, extends approximately to February 2019. | ||
4 | After that, we should coordinate with the compiler/rls developers to align goals and share code and experience. | ||
5 | |||
6 | |||
7 | # Overall Goals | ||
8 | |||
9 | The mission is: | ||
10 | * Provide an excellent "code analyzed as you type" IDE experience for the Rust language, | ||
11 | * Implement the bulk of the features in Rust itself. | ||
12 | |||
13 | |||
14 | High-level architecture constraints: | ||
15 | * Long-term, replace the current rustc frontend. | ||
16 | It's *obvious* that the code should be shared, but OTOH, all great IDEs started as from-scratch rewrites. | ||
17 | * Don't hard-code a particular protocol or mode of operation. | ||
18 | Produce a library which could be used for implementing an LSP server, or for in-process embedding. | ||
19 | * As long as possible, stick with stable Rust. | ||
20 | |||
21 | |||
22 | # Current Goals | ||
23 | |||
24 | Ideally, we would be coordinating with the compiler/rls teams, but they are busy working on making Rust 2018 at the moment. | ||
25 | The sync-up point will happen some time after the edition, probably early 2019. | ||
26 | In the meantime, the goal is to **experiment**, specifically, to figure out how a from-scratch written RLS might look like. | ||
27 | |||
28 | |||
29 | ## Data Storage and Protocol implementation | ||
30 | |||
31 | The fundamental part of any architecture is who owns which data, how the data is mutated and how the data is exposed to user. | ||
32 | For storage we use the [salsa](http://github.com/salsa-rs/salsa) library, which provides a solid model that seems to be the way to go. | ||
33 | |||
34 | Modification to source files is mostly driven by the language client, but we also should support watching the file system. The current | ||
35 | file watching implementation is a stub. | ||
36 | |||
37 | **Action Item:** implement reliable file watching service. | ||
38 | |||
39 | We also should extract LSP bits as a reusable library. There's already `gen_lsp_server`, but it is pretty limited. | ||
40 | |||
41 | **Action Item:** try using `gen_lsp_server` in more than one language server, for example for TOML and Nix. | ||
42 | |||
43 | The ideal architecture for `gen_lsp_server` is still unclear. I'd rather avoid futures: they bring significant runtime complexity | ||
44 | (call stacks become insane) and the performance benefits are negligible for our use case (one thread per request is perfectly OK given | ||
45 | the low amount of requests a language server receives). The current interface is based on crossbeam-channel, but it's not clear | ||
46 | if that is the best choice. | ||
47 | |||
48 | |||
49 | ## Low-effort, high payoff features | ||
50 | |||
51 | Implementing 20% of type inference will give use 80% of completion. | ||
52 | Thus it makes sense to partially implement name resolution, type inference and trait matching, even though there is a chance that | ||
53 | this code is replaced later on when we integrate with the compiler | ||
54 | |||
55 | Specifically, we need to: | ||
56 | |||
57 | * **Action Item:** implement path resolution, so that we get completion in imports and such. | ||
58 | * **Action Item:** implement simple type inference, so that we get completion for inherent methods. | ||
59 | * **Action Item:** implement nicer completion infrastructure, so that we have icons, snippets, doc comments, after insert callbacks, ... | ||
60 | |||
61 | |||
62 | ## Dragons to kill | ||
63 | |||
64 | To make experiments most effective, we should try to prototype solutions for the hardest problems. | ||
65 | In the case of Rust, the two hardest problems are: | ||
66 | * Conditional compilation and source/model mismatch. | ||
67 | A single source file might correspond to several entities in the semantic model. | ||
68 | For example, different cfg flags produce effectively different crates from the same source. | ||
69 | * Macros are intertwined with name resolution in a single fix-point iteration algorithm. | ||
70 | This is just plain hard to implement, but also interacts poorly with on-demand. | ||
71 | |||
72 | |||
73 | For the first bullet point, we need to design descriptors infra and explicit mapping step between sources and semantic model, which is intentionally fuzzy in one direction. | ||
74 | The **action item** here is basically "write code, see what works, keep high-level picture in mind". | ||
75 | |||
76 | For the second bullet point, there's hope that salsa with its deep memoization will result in a fast enough solution even without being fully on-demand. | ||
77 | Again, the **action item** is to write the code and see what works. Salsa itself uses macros heavily, so it should be a great test. | ||
diff --git a/docs/dev/README.md b/docs/dev/README.md new file mode 100644 index 000000000..ac7f4fd71 --- /dev/null +++ b/docs/dev/README.md | |||
@@ -0,0 +1,124 @@ | |||
1 | # Contributing Quick Start | ||
2 | |||
3 | Rust Analyzer is just a usual rust project, which is organized as a Cargo | ||
4 | workspace, builds on stable and doesn't depend on C libraries. So, just | ||
5 | |||
6 | ``` | ||
7 | $ cargo test | ||
8 | ``` | ||
9 | |||
10 | should be enough to get you started! | ||
11 | |||
12 | To learn more about how rust-analyzer works, see | ||
13 | [./architecture.md](./architecture.md) document. | ||
14 | |||
15 | Various organizational and process issues are discussed here. | ||
16 | |||
17 | # Getting in Touch | ||
18 | |||
19 | Rust Analyzer is a part of [RLS-2.0 working | ||
20 | group](https://github.com/rust-lang/compiler-team/tree/6a769c13656c0a6959ebc09e7b1f7c09b86fb9c0/working-groups/rls-2.0). | ||
21 | Discussion happens in this Zulip stream: | ||
22 | |||
23 | https://rust-lang.zulipchat.com/#narrow/stream/185405-t-compiler.2Fwg-rls-2.2E0 | ||
24 | |||
25 | # Issue Labels | ||
26 | |||
27 | * [good-first-issue](https://github.com/rust-analyzer/rust-analyzer/labels/good%20first%20issue) | ||
28 | are good issues to get into the project. | ||
29 | * [E-mentor](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-mentor) | ||
30 | issues have links to the code in question and tests. | ||
31 | * [E-easy](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy), | ||
32 | [E-medium](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-medium), | ||
33 | [E-hard](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-hard), | ||
34 | labels are *estimates* for how hard would be to write a fix. | ||
35 | * [E-fun](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-fun) | ||
36 | is for cool, but probably hard stuff. | ||
37 | |||
38 | # CI | ||
39 | |||
40 | We use Travis for CI. Most of the things, including formatting, are checked by | ||
41 | `cargo test` so, if `cargo test` passes locally, that's a good sign that CI will | ||
42 | be green as well. We use bors-ng to enforce the [not rocket | ||
43 | science](https://graydon2.dreamwidth.org/1597.html) rule. | ||
44 | |||
45 | You can run `cargo format-hook` to install git-hook to run rustfmt on commit. | ||
46 | |||
47 | # Code organization | ||
48 | |||
49 | All Rust code lives in the `crates` top-level directory, and is organized as a | ||
50 | single Cargo workspace. The `editors` top-level directory contains code for | ||
51 | integrating with editors. Currently, it contains plugins for VS Code (in | ||
52 | typescript) and Emacs (in elisp). The `docs` top-level directory contains both | ||
53 | developer and user documentation. | ||
54 | |||
55 | We have some automation infra in Rust in the `crates/tool` package. It contains | ||
56 | stuff like formatting checking, code generation and powers `cargo install-code`. | ||
57 | The latter syntax is achieved with the help of cargo aliases (see `.cargo` | ||
58 | directory). | ||
59 | |||
60 | # Launching rust-analyzer | ||
61 | |||
62 | Debugging language server can be tricky: LSP is rather chatty, so driving it | ||
63 | from the command line is not really feasible, driving it via VS Code requires | ||
64 | interacting with two processes. | ||
65 | |||
66 | For this reason, the best way to see how rust-analyzer works is to find a | ||
67 | relevant test and execute it (VS Code includes an action for running a single | ||
68 | test). | ||
69 | |||
70 | However, launching a VS Code instance with locally build language server is | ||
71 | possible. There's even a VS Code task for this, so just <kbd>F5</kbd> should | ||
72 | work (thanks, [@andrew-w-ross](https://github.com/andrew-w-ross)!). | ||
73 | |||
74 | I often just install development version with `cargo jinstall-lsp` and | ||
75 | restart the host VS Code. | ||
76 | |||
77 | See [./debugging.md](./debugging.md) for how to attach to rust-analyzer with | ||
78 | debugger, and don't forget that rust-analyzer has useful `pd` snippet and `dbg` | ||
79 | postfix completion for printf debugging :-) | ||
80 | |||
81 | # Working With VS Code Extension | ||
82 | |||
83 | To work on the VS Code extension, launch code inside `editors/code` and use `F5` | ||
84 | to launch/debug. To automatically apply formatter and linter suggestions, use | ||
85 | `npm run fix`. | ||
86 | |||
87 | # Logging | ||
88 | |||
89 | Logging is done by both rust-analyzer and VS Code, so it might be tricky to | ||
90 | figure out where logs go. | ||
91 | |||
92 | Inside rust-analyzer, we use the standard `log` crate for logging, and | ||
93 | `flexi_logger` for logging frotend. By default, log goes to stderr (the same as | ||
94 | with `env_logger`), but the stderr itself is processed by VS Code. To mirror | ||
95 | logs to a `./log` directory, set `RA_INTERNAL_MODE=1` environmental variable. | ||
96 | |||
97 | To see stderr in the running VS Code instance, go to the "Output" tab of the | ||
98 | panel and select `rust-analyzer`. This shows `eprintln!` as well. Note that | ||
99 | `stdout` is used for the actual protocol, so `println!` will break things. | ||
100 | |||
101 | To log all communication between the server and the client, there are two choices: | ||
102 | |||
103 | * you can log on the server side, by running something like | ||
104 | ``` | ||
105 | env RUST_LOG=gen_lsp_server=trace code . | ||
106 | ``` | ||
107 | |||
108 | * you can log on the client side, by enabling `"rust-analyzer.trace.server": | ||
109 | "verbose"` workspace setting. These logs are shown in a separate tab in the | ||
110 | output and could be used with LSP inspector. Kudos to | ||
111 | [@DJMcNab](https://github.com/DJMcNab) for setting this awesome infra up! | ||
112 | |||
113 | |||
114 | There's also two VS Code commands which might be of interest: | ||
115 | |||
116 | * `Rust Analyzer: Status` shows some memory-usage statistics. To take full | ||
117 | advantage of it, you need to compile rust-analyzer with jemalloc support: | ||
118 | ``` | ||
119 | $ cargo install --path crates/ra_lsp_server --force --features jemalloc | ||
120 | ``` | ||
121 | |||
122 | There's an alias for this: `cargo jinstall-lsp`. | ||
123 | |||
124 | * `Rust Analyzer: Syntax Tree` shows syntax tree of the current file/selection. | ||
diff --git a/ARCHITECTURE.md b/docs/dev/architecture.md index 57f76ebae..f990d5bf0 100644 --- a/ARCHITECTURE.md +++ b/docs/dev/architecture.md | |||
@@ -7,8 +7,10 @@ in the right place! | |||
7 | See also the [guide](./guide.md), which walks through a particular snapshot of | 7 | See also the [guide](./guide.md), which walks through a particular snapshot of |
8 | rust-analyzer code base. | 8 | rust-analyzer code base. |
9 | 9 | ||
10 | For syntax-trees specifically, there's a [video walk | 10 | Yet another resource is this playlist with videos about various parts of the |
11 | through](https://youtu.be/DGAuLWdCCAI) as well. | 11 | analyzer: |
12 | |||
13 | https://www.youtube.com/playlist?list=PL85XCvVPmGQho7MZkdW-wtPtuJcFpzycE | ||
12 | 14 | ||
13 | ## The Big Picture | 15 | ## The Big Picture |
14 | 16 | ||
@@ -61,7 +63,7 @@ processes. These are outlined below: | |||
61 | 63 | ||
62 | ## Code Walk-Through | 64 | ## Code Walk-Through |
63 | 65 | ||
64 | ### `crates/ra_syntax` | 66 | ### `crates/ra_syntax`, `crates/ra_parser` |
65 | 67 | ||
66 | Rust syntax tree structure and parser. See | 68 | Rust syntax tree structure and parser. See |
67 | [RFC](https://github.com/rust-lang/rfcs/pull/2256) for some design notes. | 69 | [RFC](https://github.com/rust-lang/rfcs/pull/2256) for some design notes. |
@@ -145,12 +147,14 @@ throughout its modules. | |||
145 | 147 | ||
146 | An LSP implementation which wraps `ra_ide_api` into a langauge server protocol. | 148 | An LSP implementation which wraps `ra_ide_api` into a langauge server protocol. |
147 | 149 | ||
148 | ### `crates/ra_vfs` | 150 | ### `ra_vfs` |
149 | 151 | ||
150 | Although `hir` and `ra_ide_api` don't do any IO, we need to be able to read | 152 | Although `hir` and `ra_ide_api` don't do any IO, we need to be able to read |
151 | files from disk at the end of the day. This is what `ra_vfs` does. It also | 153 | files from disk at the end of the day. This is what `ra_vfs` does. It also |
152 | manages overlays: "dirty" files in the editor, whose "true" contents is | 154 | manages overlays: "dirty" files in the editor, whose "true" contents is |
153 | different from data on disk. | 155 | different from data on disk. This is more or less the single really |
156 | platform-dependent component, so it lives in a separate repository and has an | ||
157 | extensive cross-platform CI testing. | ||
154 | 158 | ||
155 | ### `crates/gen_lsp_server` | 159 | ### `crates/gen_lsp_server` |
156 | 160 | ||
@@ -164,37 +168,32 @@ Run with `RUST_LOG=sync_lsp_server=debug` to see all the messages. | |||
164 | 168 | ||
165 | A CLI interface to rust-analyzer. | 169 | A CLI interface to rust-analyzer. |
166 | 170 | ||
167 | ### `crate/tools` | ||
168 | |||
169 | Custom Cargo tasks used to develop rust-analyzer: | ||
170 | |||
171 | - `cargo gen-syntax` -- generate `ast` and `syntax_kinds` | ||
172 | - `cargo gen-tests` -- collect inline tests from grammar | ||
173 | - `cargo install-code` -- build and install VS Code extension and server | ||
174 | |||
175 | ### `editors/code` | ||
176 | |||
177 | VS Code plugin | ||
178 | 171 | ||
172 | ## Testing Infrastructure | ||
179 | 173 | ||
180 | ## Common workflows | 174 | Rust Analyzer has three interesting [systems |
175 | boundaries](https://www.tedinski.com/2018/04/10/making-tests-a-positive-influence-on-design.html) | ||
176 | to concentrate tests on. | ||
181 | 177 | ||
182 | To try out VS Code extensions, run `cargo install-code`. This installs both the | 178 | The outermost boundary is the `ra_lsp_server` crate, which defines an LSP |
183 | `ra_lsp_server` binary and the VS Code extension. To install only the binary, use | 179 | interface in terms of stdio. We do integration testing of this component, by |
184 | `cargo install-lsp` (shorthand for `cargo install --path crates/ra_lsp_server --force`) | 180 | feeding it with a stream of LSP requests and checking responses. These tests are |
181 | known as "heavy", because they interact with Cargo and read real files from | ||
182 | disk. For this reason, we try to avoid writing too many tests on this boundary: | ||
183 | in a statically typed language, it's hard to make an error in the protocol | ||
184 | itself if messages are themselves typed. | ||
185 | 185 | ||
186 | To see logs from the language server, set `RUST_LOG=info` env variable. To see | 186 | The middle, and most important, boundary is `ra_ide_api`. Unlike |
187 | all communication between the server and the client, use | 187 | `ra_lsp_server`, which exposes API, `ide_api` uses Rust API and is intended to |
188 | `RUST_LOG=gen_lsp_server=debug` (this will print quite a bit of stuff). | 188 | use by various tools. Typical test creates an `AnalysisHost`, calls some |
189 | `Analysis` functions and compares the results against expectation. | ||
189 | 190 | ||
190 | There's `rust-analyzer: status` command which prints common high-level debug | 191 | The innermost and most elaborate boundary is `hir`. It has a much richer |
191 | info. In particular, it prints info about memory usage of various data | 192 | vocabulary of types than `ide_api`, but the basic testing setup is the same: we |
192 | structures, and, if compiled with jemalloc support (`cargo jinstall-lsp` or | 193 | create a database, run some queries, assert result. |
193 | `cargo install --path crates/ra_lsp_server --force --features jemalloc`), includes | ||
194 | statistic about the heap. | ||
195 | 194 | ||
196 | To run tests, just `cargo test`. | 195 | For comparisons, we use [insta](https://github.com/mitsuhiko/insta/) library for |
196 | snapshot testing. | ||
197 | 197 | ||
198 | To work on the VS Code extension, launch code inside `editors/code` and use `F5` to | 198 | To test various analysis corner cases and avoid forgetting about old tests, we |
199 | launch/debug. To automatically apply formatter and linter suggestions, use `npm | 199 | use so-called marks. See the `marks` module in the `test_utils` crate for more. |
200 | run fix`. | ||
diff --git a/DEBUGGING.md b/docs/dev/debugging.md index f868e6998..f868e6998 100644 --- a/DEBUGGING.md +++ b/docs/dev/debugging.md | |||
diff --git a/guide.md b/docs/dev/guide.md index abbe4c154..abbe4c154 100644 --- a/guide.md +++ b/docs/dev/guide.md | |||
diff --git a/docs/dev/lsp-features.md b/docs/dev/lsp-features.md new file mode 100644 index 000000000..212d132ee --- /dev/null +++ b/docs/dev/lsp-features.md | |||
@@ -0,0 +1,74 @@ | |||
1 | # Supported LSP features | ||
2 | |||
3 | This list documents LSP features, supported by rust-analyzer. | ||
4 | |||
5 | ## General | ||
6 | - [x] [initialize](https://microsoft.github.io/language-server-protocol/specification#initialize) | ||
7 | - [x] [initialized](https://microsoft.github.io/language-server-protocol/specification#initialized) | ||
8 | - [x] [shutdown](https://microsoft.github.io/language-server-protocol/specification#shutdown) | ||
9 | - [ ] [exit](https://microsoft.github.io/language-server-protocol/specification#exit) | ||
10 | - [x] [$/cancelRequest](https://microsoft.github.io/language-server-protocol/specification#cancelRequest) | ||
11 | |||
12 | ## Workspace | ||
13 | - [ ] [workspace/workspaceFolders](https://microsoft.github.io/language-server-protocol/specification#workspace_workspaceFolders) | ||
14 | - [ ] [workspace/didChangeWorkspaceFolders](https://microsoft.github.io/language-server-protocol/specification#workspace_didChangeWorkspaceFolders) | ||
15 | - [x] [workspace/didChangeConfiguration](https://microsoft.github.io/language-server-protocol/specification#workspace_didChangeConfiguration) | ||
16 | - [ ] [workspace/configuration](https://microsoft.github.io/language-server-protocol/specification#workspace_configuration) | ||
17 | - [x] [workspace/didChangeWatchedFiles](https://microsoft.github.io/language-server-protocol/specification#workspace_didChangeWatchedFiles) | ||
18 | - [x] [workspace/symbol](https://microsoft.github.io/language-server-protocol/specification#workspace_symbol) | ||
19 | - [x] [workspace/executeCommand](https://microsoft.github.io/language-server-protocol/specification#workspace_executeCommand) | ||
20 | - `apply_code_action` | ||
21 | - [ ] [workspace/applyEdit](https://microsoft.github.io/language-server-protocol/specification#workspace_applyEdit) | ||
22 | |||
23 | ## Text Synchronization | ||
24 | - [x] [textDocument/didOpen](https://microsoft.github.io/language-server-protocol/specification#textDocument_didOpen) | ||
25 | - [x] [textDocument/didChange](https://microsoft.github.io/language-server-protocol/specification#textDocument_didChange) | ||
26 | - [ ] [textDocument/willSave](https://microsoft.github.io/language-server-protocol/specification#textDocument_willSave) | ||
27 | - [ ] [textDocument/willSaveWaitUntil](https://microsoft.github.io/language-server-protocol/specification#textDocument_willSaveWaitUntil) | ||
28 | - [x] [textDocument/didSave](https://microsoft.github.io/language-server-protocol/specification#textDocument_didSave) | ||
29 | - [x] [textDocument/didClose](https://microsoft.github.io/language-server-protocol/specification#textDocument_didClose) | ||
30 | |||
31 | ## Diagnostics | ||
32 | - [x] [textDocument/publishDiagnostics](https://microsoft.github.io/language-server-protocol/specification#textDocument_publishDiagnostics) | ||
33 | |||
34 | ## Lanuguage Features | ||
35 | - [x] [textDocument/completion](https://microsoft.github.io/language-server-protocol/specification#textDocument_completion) | ||
36 | - open close: false | ||
37 | - change: Full | ||
38 | - will save: false | ||
39 | - will save wait until: false | ||
40 | - save: false | ||
41 | - [x] [completionItem/resolve](https://microsoft.github.io/language-server-protocol/specification#completionItem_resolve) | ||
42 | - resolve provider: none | ||
43 | - trigger characters: `:`, `.` | ||
44 | - [x] [textDocument/hover](https://microsoft.github.io/language-server-protocol/specification#textDocument_hover) | ||
45 | - [x] [textDocument/signatureHelp](https://microsoft.github.io/language-server-protocol/specification#textDocument_signatureHelp) | ||
46 | - trigger characters: `(`, `,`, `)` | ||
47 | - [ ] [textDocument/declaration](https://microsoft.github.io/language-server-protocol/specification#textDocument_declaration) | ||
48 | - [x] [textDocument/definition](https://microsoft.github.io/language-server-protocol/specification#textDocument_definition) | ||
49 | - [ ] [textDocument/typeDefinition](https://microsoft.github.io/language-server-protocol/specification#textDocument_typeDefinition) | ||
50 | - [x] [textDocument/implementation](https://microsoft.github.io/language-server-protocol/specification#textDocument_implementation) | ||
51 | - [x] [textDocument/references](https://microsoft.github.io/language-server-protocol/specification#textDocument_references) | ||
52 | - [x] [textDocument/documentHighlight](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentHighlight) | ||
53 | - [x] [textDocument/documentSymbol](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentSymbol) | ||
54 | - [x] [textDocument/codeAction](https://microsoft.github.io/language-server-protocol/specification#textDocument_codeAction) | ||
55 | - rust-analyzer.syntaxTree | ||
56 | - rust-analyzer.extendSelection | ||
57 | - rust-analyzer.matchingBrace | ||
58 | - rust-analyzer.parentModule | ||
59 | - rust-analyzer.joinLines | ||
60 | - rust-analyzer.run | ||
61 | - rust-analyzer.analyzerStatus | ||
62 | - [x] [textDocument/codeLens](https://microsoft.github.io/language-server-protocol/specification#textDocument_codeLens) | ||
63 | - [ ] [textDocument/documentLink](https://microsoft.github.io/language-server-protocol/specification#codeLens_resolve) | ||
64 | - [ ] [documentLink/resolve](https://microsoft.github.io/language-server-protocol/specification#documentLink_resolve) | ||
65 | - [ ] [textDocument/documentColor](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentColor) | ||
66 | - [ ] [textDocument/colorPresentation](https://microsoft.github.io/language-server-protocol/specification#textDocument_colorPresentation) | ||
67 | - [x] [textDocument/formatting](https://microsoft.github.io/language-server-protocol/specification#textDocument_formatting) | ||
68 | - [ ] [textDocument/rangeFormatting](https://microsoft.github.io/language-server-protocol/specification#textDocument_rangeFormatting) | ||
69 | - [x] [textDocument/onTypeFormatting](https://microsoft.github.io/language-server-protocol/specification#textDocument_onTypeFormatting) | ||
70 | - first trigger character: `=` | ||
71 | - more trigger character `.` | ||
72 | - [x] [textDocument/rename](https://microsoft.github.io/language-server-protocol/specification#textDocument_rename) | ||
73 | - [x] [textDocument/prepareRename](https://microsoft.github.io/language-server-protocol/specification#textDocument_prepareRename) | ||
74 | - [x] [textDocument/foldingRange](https://microsoft.github.io/language-server-protocol/specification#textDocument_foldingRange) | ||
diff --git a/docs/user/README.md b/docs/user/README.md new file mode 100644 index 000000000..439c4e6ae --- /dev/null +++ b/docs/user/README.md | |||
@@ -0,0 +1,77 @@ | |||
1 | The main interface to rust-analyzer is the | ||
2 | [LSP](https://microsoft.github.io/language-server-protocol/) implementation. To | ||
3 | install lsp server, use `cargo install-lsp`, which is a shorthand for `cargo | ||
4 | install --package ra_lsp_server`. The binary is named `ra_lsp_server`, you | ||
5 | should be able to use it with any LSP-compatible editor. We use custom | ||
6 | extensions to LSP, so special client-side support is required to take full | ||
7 | advantage of rust-analyzer. This repository contains support code for VS Code | ||
8 | and Emacs. | ||
9 | |||
10 | Rust Analyzer needs sources of rust standard library to work, so you might need | ||
11 | to execute | ||
12 | |||
13 | ``` | ||
14 | $ rustup component add rust-src | ||
15 | ``` | ||
16 | |||
17 | See [./features.md](./features.md) document for a list of features that are available. | ||
18 | |||
19 | ## VS Code | ||
20 | |||
21 | Prerequisites: | ||
22 | |||
23 | In order to build the VS Code plugin, you need to have node.js and npm with | ||
24 | a minimum version of 10 installed. Please refer to | ||
25 | [node.js and npm documentation](https://nodejs.org) for installation instructions. | ||
26 | |||
27 | You will also need the most recent version of VS Code: we don't try to | ||
28 | maintain compatibility with older versions yet. | ||
29 | |||
30 | The experimental VS Code plugin can then be built and installed by executing the | ||
31 | following commands: | ||
32 | |||
33 | ``` | ||
34 | $ git clone https://github.com/rust-analyzer/rust-analyzer.git --depth 1 | ||
35 | $ cd rust-analyzer | ||
36 | $ cargo install-code | ||
37 | ``` | ||
38 | |||
39 | This will run `cargo install --package ra_lsp_server` to install the server | ||
40 | binary into `~/.cargo/bin`, and then will build and install plugin from | ||
41 | `editors/code`. See | ||
42 | [this](https://github.com/rust-analyzer/rust-analyzer/blob/69ee5c9c5ef212f7911028c9ddf581559e6565c3/crates/tools/src/main.rs#L37-L56) | ||
43 | for details. The installation is expected to *just work*, if it doesn't, report | ||
44 | bugs! | ||
45 | |||
46 | It's better to remove existing Rust plugins to avoid interference. | ||
47 | |||
48 | Beyond basic LSP features, there are some extension commands which you can | ||
49 | invoke via <kbd>Ctrl+Shift+P</kbd> or bind to a shortcut. See [./features.md](./features.md) | ||
50 | for details. | ||
51 | |||
52 | ### Settings | ||
53 | |||
54 | * `rust-analyzer.highlightingOn`: enables experimental syntax highlighting | ||
55 | * `rust-analyzer.showWorkspaceLoadedNotification`: to ease troubleshooting, a | ||
56 | notification is shown by default when a workspace is loaded | ||
57 | * `rust-analyzer.enableEnhancedTyping`: by default, rust-analyzer intercepts | ||
58 | `Enter` key to make it easier to continue comments | ||
59 | * `rust-analyzer.raLspServerPath`: path to `ra_lsp_server` executable | ||
60 | * `rust-analyzer.enableCargoWatchOnStartup`: prompt to install & enable `cargo | ||
61 | watch` for live error highlighting (note, this **does not** use rust-analyzer) | ||
62 | * `rust-analyzer.trace.server`: enables internal logging | ||
63 | |||
64 | |||
65 | ## Emacs | ||
66 | |||
67 | Prerequisites: | ||
68 | |||
69 | `emacs-lsp`, `dash` and `ht` packages. | ||
70 | |||
71 | Installation: | ||
72 | |||
73 | * add | ||
74 | [ra-emacs-lsp.el](https://github.com/rust-analyzer/rust-analyzer/blob/69ee5c9c5ef212f7911028c9ddf581559e6565c3/editors/emacs/ra-emacs-lsp.el) | ||
75 | to load path and require it in `init.el` | ||
76 | * run `lsp` in a rust buffer | ||
77 | * (Optionally) bind commands like `rust-analyzer-join-lines` or `rust-analyzer-extend-selection` to keys | ||
diff --git a/docs/user/features.md b/docs/user/features.md new file mode 100644 index 000000000..b9d2aa84f --- /dev/null +++ b/docs/user/features.md | |||
@@ -0,0 +1,359 @@ | |||
1 | This documents is an index of features that rust-analyzer language server | ||
2 | provides. Shortcuts are for the default VS Code layout. If there's no shortcut, | ||
3 | you can use <kbd>Ctrl+Shift+P</kbd> to search for the corresponding action. | ||
4 | |||
5 | ### Workspace Symbol <kbd>ctrl+t</kbd> | ||
6 | |||
7 | Uses fuzzy-search to find types, modules and function by name across your | ||
8 | project and dependencies. This **the** most useful feature, which improves code | ||
9 | navigation tremendously. It mostly works on top of the built-in LSP | ||
10 | functionality, however `#` and `*` symbols can be used to narrow down the | ||
11 | search. Specifically, | ||
12 | |||
13 | - `Foo` searches for `Foo` type in the current workspace | ||
14 | - `foo#` searches for `foo` function in the current workspace | ||
15 | - `Foo*` searches for `Foo` type among dependencies, excluding `stdlib` | ||
16 | - `foo#*` searches for `foo` function among dependencies. | ||
17 | |||
18 | That is, `#` switches from "types" to all symbols, `*` switches from the current | ||
19 | workspace to dependencies. | ||
20 | |||
21 | ### Document Symbol <kbd>ctrl+shift+o</kbd> | ||
22 | |||
23 | Provides a tree of the symbols defined in the file. Can be used to | ||
24 | |||
25 | * fuzzy search symbol in a file (super useful) | ||
26 | * draw breadcrumbs to describe the context around the cursor | ||
27 | * draw outline of the file | ||
28 | |||
29 | ### On Typing Assists | ||
30 | |||
31 | Some features trigger on typing certain characters: | ||
32 | |||
33 | - typing `let =` tries to smartly add `;` if `=` is followed by an existing expression. | ||
34 | - Enter inside comments automatically inserts `///` | ||
35 | - typing `.` in a chain method call auto-indents | ||
36 | |||
37 | ### Commands <kbd>ctrl+shift+p</kbd> | ||
38 | |||
39 | #### Extend Selection | ||
40 | |||
41 | Extends the current selection to the encompassing syntactic construct | ||
42 | (expression, statement, item, module, etc). It works with multiple cursors. Do | ||
43 | bind this command to a key, it's super-useful! Expected to be upstreamed to LSP | ||
44 | soonish: https://github.com/Microsoft/language-server-protocol/issues/613 | ||
45 | |||
46 | #### Run | ||
47 | |||
48 | Shows popup suggesting to run a test/benchmark/binary **at the current cursor | ||
49 | location**. Super useful for repeatedly running just a single test. Do bind this | ||
50 | to a shortcut! | ||
51 | |||
52 | #### Parent Module | ||
53 | |||
54 | Navigates to the parent module of the current module. | ||
55 | |||
56 | #### Matching Brace | ||
57 | |||
58 | If the cursor is on any brace (`<>(){}[]`) which is a part of a brace-pair, | ||
59 | moves cursor to the matching brace. It uses the actual parser to determine | ||
60 | braces, so it won't confuse generics with comparisons. | ||
61 | |||
62 | #### Join Lines | ||
63 | |||
64 | Join selected lines into one, smartly fixing up whitespace and trailing commas. | ||
65 | |||
66 | #### Show Syntax Tree | ||
67 | |||
68 | Shows the parse tree of the current file. It exists mostly for debugging | ||
69 | rust-analyzer itself. | ||
70 | |||
71 | #### Status | ||
72 | |||
73 | Shows internal statistic about memory usage of rust-analyzer | ||
74 | |||
75 | #### Run garbage collection | ||
76 | |||
77 | Manually triggers GC | ||
78 | |||
79 | ### Code Actions (Assists) | ||
80 | |||
81 | These are triggered in a particular context via light bulb. We use custom code on | ||
82 | the VS Code side to be able to position cursor. `<|>` signifies cursor | ||
83 | |||
84 | - Add `#[derive]` | ||
85 | |||
86 | ```rust | ||
87 | // before: | ||
88 | struct Foo { | ||
89 | <|>x: i32 | ||
90 | } | ||
91 | // after: | ||
92 | #[derive(<|>)] | ||
93 | struct Foo { | ||
94 | x: i32 | ||
95 | } | ||
96 | ``` | ||
97 | |||
98 | - Add `impl` | ||
99 | |||
100 | ```rust | ||
101 | // before: | ||
102 | struct Foo<'a, T: Debug> { | ||
103 | <|>t: T | ||
104 | } | ||
105 | // after: | ||
106 | struct Foo<'a, T: Debug> { | ||
107 | t: T | ||
108 | } | ||
109 | |||
110 | impl<'a, T: Debug> Foo<'a, T> { | ||
111 | <|> | ||
112 | } | ||
113 | ``` | ||
114 | |||
115 | - Add missing `impl` members | ||
116 | |||
117 | ```rust | ||
118 | // before: | ||
119 | trait Foo { | ||
120 | fn foo(&self); | ||
121 | fn bar(&self); | ||
122 | fn baz(&self); | ||
123 | } | ||
124 | |||
125 | struct S; | ||
126 | |||
127 | impl Foo for S { | ||
128 | fn bar(&self) {} | ||
129 | <|> | ||
130 | } | ||
131 | |||
132 | // after: | ||
133 | trait Foo { | ||
134 | fn foo(&self); | ||
135 | fn bar(&self); | ||
136 | fn baz(&self); | ||
137 | } | ||
138 | |||
139 | struct S; | ||
140 | |||
141 | impl Foo for S { | ||
142 | fn bar(&self) {} | ||
143 | fn foo(&self) { unimplemented!() } | ||
144 | fn baz(&self) { unimplemented!() }<|> | ||
145 | } | ||
146 | ``` | ||
147 | |||
148 | - Import path | ||
149 | |||
150 | ```rust | ||
151 | // before: | ||
152 | impl std::fmt::Debug<|> for Foo { | ||
153 | } | ||
154 | |||
155 | // after: | ||
156 | use std::fmt::Debug; | ||
157 | |||
158 | impl Debug<|> for Foo { | ||
159 | } | ||
160 | ``` | ||
161 | |||
162 | - Change Visibility | ||
163 | |||
164 | ```rust | ||
165 | // before: | ||
166 | <|>fn foo() {} | ||
167 | |||
168 | // after: | ||
169 | <|>pub(crate) fn foo() {} | ||
170 | |||
171 | // after: | ||
172 | <|>pub fn foo() {} | ||
173 | ``` | ||
174 | |||
175 | - Fill match arms | ||
176 | |||
177 | ```rust | ||
178 | // before: | ||
179 | enum A { | ||
180 | As, | ||
181 | Bs, | ||
182 | Cs(String), | ||
183 | Ds(String, String), | ||
184 | Es{x: usize, y: usize} | ||
185 | } | ||
186 | |||
187 | fn main() { | ||
188 | let a = A::As; | ||
189 | match a<|> {} | ||
190 | } | ||
191 | |||
192 | // after: | ||
193 | enum A { | ||
194 | As, | ||
195 | Bs, | ||
196 | Cs(String), | ||
197 | Ds(String, String), | ||
198 | Es{x: usize, y: usize} | ||
199 | } | ||
200 | |||
201 | fn main() { | ||
202 | let a = A::As; | ||
203 | match <|>a { | ||
204 | A::As => (), | ||
205 | A::Bs => (), | ||
206 | A::Cs(_) => (), | ||
207 | A::Ds(_, _) => (), | ||
208 | A::Es{x, y} => (), | ||
209 | } | ||
210 | } | ||
211 | ``` | ||
212 | |||
213 | -- Fill struct fields | ||
214 | |||
215 | ```rust | ||
216 | // before: | ||
217 | struct S<'a, D> { | ||
218 | a: u32, | ||
219 | b: String, | ||
220 | c: (i32, i32), | ||
221 | d: D, | ||
222 | r: &'a str, | ||
223 | } | ||
224 | |||
225 | fn main() { | ||
226 | let s = S<|> {} | ||
227 | } | ||
228 | |||
229 | // after: | ||
230 | struct S<'a, D> { | ||
231 | a: u32, | ||
232 | b: String, | ||
233 | c: (i32, i32), | ||
234 | d: D, | ||
235 | r: &'a str, | ||
236 | } | ||
237 | |||
238 | fn main() { | ||
239 | let s = <|>S { | ||
240 | a: (), | ||
241 | b: (), | ||
242 | c: (), | ||
243 | d: (), | ||
244 | r: (), | ||
245 | } | ||
246 | } | ||
247 | ``` | ||
248 | |||
249 | - Flip `,` | ||
250 | |||
251 | ```rust | ||
252 | // before: | ||
253 | fn foo(x: usize,<|> dim: (usize, usize)) {} | ||
254 | // after: | ||
255 | fn foo(dim: (usize, usize), x: usize) {} | ||
256 | ``` | ||
257 | |||
258 | - Introduce variable: | ||
259 | |||
260 | ```rust | ||
261 | // before: | ||
262 | fn foo() { | ||
263 | foo(<|>1 + 1<|>); | ||
264 | } | ||
265 | |||
266 | // after: | ||
267 | fn foo() { | ||
268 | let var_name = 1 + 1; | ||
269 | foo(var_name); | ||
270 | } | ||
271 | ``` | ||
272 | |||
273 | -- Remove `dbg!` | ||
274 | |||
275 | ```rust | ||
276 | // before: | ||
277 | fn foo(n: usize) { | ||
278 | if let Some(_) = dbg!(n.<|>checked_sub(4)) { | ||
279 | // ... | ||
280 | } | ||
281 | } | ||
282 | |||
283 | // after: | ||
284 | fn foo(n: usize) { | ||
285 | if let Some(_) = n.<|>checked_sub(4) { | ||
286 | // ... | ||
287 | } | ||
288 | } | ||
289 | ``` | ||
290 | |||
291 | - Replace if-let with match: | ||
292 | |||
293 | ```rust | ||
294 | // before: | ||
295 | impl VariantData { | ||
296 | pub fn is_struct(&self) -> bool { | ||
297 | if <|>let VariantData::Struct(..) = *self { | ||
298 | true | ||
299 | } else { | ||
300 | false | ||
301 | } | ||
302 | } | ||
303 | } | ||
304 | |||
305 | // after: | ||
306 | impl VariantData { | ||
307 | pub fn is_struct(&self) -> bool { | ||
308 | <|>match *self { | ||
309 | VariantData::Struct(..) => true, | ||
310 | _ => false, | ||
311 | } | ||
312 | } | ||
313 | } | ||
314 | ``` | ||
315 | |||
316 | - Split import | ||
317 | |||
318 | ```rust | ||
319 | // before: | ||
320 | use algo:<|>:visitor::{Visitor, visit}; | ||
321 | //after: | ||
322 | use algo::{<|>visitor::{Visitor, visit}}; | ||
323 | ``` | ||
324 | |||
325 | ### Magic Completions | ||
326 | |||
327 | In addition to usual reference completion, rust-analyzer provides some ✨magic✨ | ||
328 | completions as well: | ||
329 | |||
330 | Keywords like `if`, `else` `while`, `loop` are completed with braces, and cursor | ||
331 | is placed at the appropriate position. Even though `if` is easy to type, you | ||
332 | still want to complete it, to get ` { }` for free! `return` is inserted with a | ||
333 | space or `;` depending on the return type of the function. | ||
334 | |||
335 | When completing a function call, `()` are automatically inserted. If function | ||
336 | takes arguments, cursor is positioned inside the parenthesis. | ||
337 | |||
338 | There are postifx completions, which can be triggerd by typing something like | ||
339 | `foo().if`. The word after `.` determines postifx completion, possible variants are: | ||
340 | |||
341 | - `expr.if` -> `if expr {}` | ||
342 | - `expr.match` -> `match expr {}` | ||
343 | - `expr.while` -> `while expr {}` | ||
344 | - `expr.ref` -> `&expr` | ||
345 | - `expr.refm` -> `&mut expr` | ||
346 | - `expr.not` -> `!expr` | ||
347 | - `expr.dbg` -> `dbg!(expr)` | ||
348 | |||
349 | There also snippet completions: | ||
350 | |||
351 | #### Inside Expressions | ||
352 | |||
353 | - `pd` -> `println!("{:?}")` | ||
354 | - `ppd` -> `println!("{:#?}")` | ||
355 | |||
356 | #### Inside Modules | ||
357 | |||
358 | - `tfn` -> `#[test] fn f(){}` | ||
359 | |||
diff --git a/editors/README.md b/editors/README.md deleted file mode 100644 index ddc6ee048..000000000 --- a/editors/README.md +++ /dev/null | |||
@@ -1,241 +0,0 @@ | |||
1 | |||
2 | Prerequisites: | ||
3 | |||
4 | In order to build the VS Code plugin, you need to have node.js and npm with | ||
5 | a minimum version of 10 installed. Please refer to | ||
6 | [node.js and npm documentation](https://nodejs.org) for installation instructions. | ||
7 | |||
8 | You will also need the most recent version of VS Code: we don't try to | ||
9 | maintain compatibility with older versions yet. | ||
10 | |||
11 | The experimental VS Code plugin can then be built and installed by executing the | ||
12 | following commands: | ||
13 | |||
14 | ``` | ||
15 | $ git clone https://github.com/rust-analyzer/rust-analyzer.git --depth 1 | ||
16 | $ cd rust-analyzer | ||
17 | $ cargo install-code | ||
18 | |||
19 | # for stdlib support | ||
20 | $ rustup component add rust-src | ||
21 | ``` | ||
22 | |||
23 | This will run `cargo install --package ra_lsp_server` to install the server | ||
24 | binary into `~/.cargo/bin`, and then will build and install plugin from | ||
25 | `editors/code`. See | ||
26 | [this](https://github.com/rust-analyzer/rust-analyzer/blob/0199572a3d06ff66eeae85a2d2c9762996f0d2d8/crates/tools/src/main.rs#L150) | ||
27 | for details. The installation is expected to *just work*, if it doesn't, report | ||
28 | bugs! | ||
29 | |||
30 | It's better to remove existing Rust plugins to avoid interference. | ||
31 | |||
32 | ## Rust Analyzer Specific Features | ||
33 | |||
34 | These features are implemented as extensions to the language server protocol. | ||
35 | They are more experimental in nature and work only with VS Code. | ||
36 | |||
37 | ### Syntax highlighting | ||
38 | |||
39 | It overrides built-in highlighting, and works only with a specific theme | ||
40 | (zenburn). `rust-analyzer.highlightingOn` setting can be used to disable it. | ||
41 | |||
42 | ### Go to symbol in workspace <kbd>ctrl+t</kbd> | ||
43 | |||
44 | It mostly works on top of the built-in LSP functionality, however `#` and `*` | ||
45 | symbols can be used to narrow down the search. Specifically, | ||
46 | |||
47 | - `#Foo` searches for `Foo` type in the current workspace | ||
48 | - `#foo#` searches for `foo` function in the current workspace | ||
49 | - `#Foo*` searches for `Foo` type among dependencies, excluding `stdlib` | ||
50 | - `#foo#*` searches for `foo` function among dependencies. | ||
51 | |||
52 | That is, `#` switches from "types" to all symbols, `*` switches from the current | ||
53 | workspace to dependencies. | ||
54 | |||
55 | ### Commands <kbd>ctrl+shift+p</kbd> | ||
56 | |||
57 | #### Show Rust Syntax Tree | ||
58 | |||
59 | Shows the parse tree of the current file. It exists mostly for debugging | ||
60 | rust-analyzer itself. | ||
61 | |||
62 | #### Extend Selection | ||
63 | |||
64 | Extends the current selection to the encompassing syntactic construct | ||
65 | (expression, statement, item, module, etc). It works with multiple cursors. Do | ||
66 | bind this command to a key, its super-useful! Expected to be upstreamed to LSP soonish: | ||
67 | https://github.com/Microsoft/language-server-protocol/issues/613 | ||
68 | |||
69 | #### Matching Brace | ||
70 | |||
71 | If the cursor is on any brace (`<>(){}[]`) which is a part of a brace-pair, | ||
72 | moves cursor to the matching brace. It uses the actual parser to determine | ||
73 | braces, so it won't confuse generics with comparisons. | ||
74 | |||
75 | #### Parent Module | ||
76 | |||
77 | Navigates to the parent module of the current module. | ||
78 | |||
79 | #### Join Lines | ||
80 | |||
81 | Join selected lines into one, smartly fixing up whitespace and trailing commas. | ||
82 | |||
83 | #### Run | ||
84 | |||
85 | Shows popup suggesting to run a test/benchmark/binary **at the current cursor | ||
86 | location**. Super useful for repeatedly running just a single test. Do bind this | ||
87 | to a shortcut! | ||
88 | |||
89 | |||
90 | ### On Typing Assists | ||
91 | |||
92 | Some features trigger on typing certain characters: | ||
93 | |||
94 | - typing `let =` tries to smartly add `;` if `=` is followed by an existing expression. | ||
95 | - Enter inside comments automatically inserts `///` | ||
96 | - typing `.` in a chain method call auto-indents | ||
97 | |||
98 | |||
99 | ### Code Actions (Assists) | ||
100 | |||
101 | These are triggered in a particular context via light bulb. We use custom code on | ||
102 | the VS Code side to be able to position cursor. | ||
103 | |||
104 | |||
105 | - Flip `,` | ||
106 | |||
107 | ```rust | ||
108 | // before: | ||
109 | fn foo(x: usize,<|> dim: (usize, usize)) | ||
110 | // after: | ||
111 | fn foo(dim: (usize, usize), x: usize) | ||
112 | ``` | ||
113 | |||
114 | - Add `#[derive]` | ||
115 | |||
116 | ```rust | ||
117 | // before: | ||
118 | struct Foo { | ||
119 | <|>x: i32 | ||
120 | } | ||
121 | // after: | ||
122 | #[derive(<|>)] | ||
123 | struct Foo { | ||
124 | x: i32 | ||
125 | } | ||
126 | ``` | ||
127 | |||
128 | - Add `impl` | ||
129 | |||
130 | ```rust | ||
131 | // before: | ||
132 | struct Foo<'a, T: Debug> { | ||
133 | <|>t: T | ||
134 | } | ||
135 | // after: | ||
136 | struct Foo<'a, T: Debug> { | ||
137 | t: T | ||
138 | } | ||
139 | |||
140 | impl<'a, T: Debug> Foo<'a, T> { | ||
141 | <|> | ||
142 | } | ||
143 | ``` | ||
144 | |||
145 | - Change visibility | ||
146 | |||
147 | ```rust | ||
148 | // before: | ||
149 | fn<|> foo() {} | ||
150 | |||
151 | // after | ||
152 | pub(crate) fn foo() {} | ||
153 | ``` | ||
154 | |||
155 | - Introduce variable: | ||
156 | |||
157 | ```rust | ||
158 | // before: | ||
159 | fn foo() { | ||
160 | foo(<|>1 + 1<|>); | ||
161 | } | ||
162 | |||
163 | // after: | ||
164 | fn foo() { | ||
165 | let var_name = 1 + 1; | ||
166 | foo(var_name); | ||
167 | } | ||
168 | ``` | ||
169 | |||
170 | - Replace if-let with match: | ||
171 | |||
172 | ```rust | ||
173 | // before: | ||
174 | impl VariantData { | ||
175 | pub fn is_struct(&self) -> bool { | ||
176 | if <|>let VariantData::Struct(..) = *self { | ||
177 | true | ||
178 | } else { | ||
179 | false | ||
180 | } | ||
181 | } | ||
182 | } | ||
183 | |||
184 | // after: | ||
185 | impl VariantData { | ||
186 | pub fn is_struct(&self) -> bool { | ||
187 | <|>match *self { | ||
188 | VariantData::Struct(..) => true, | ||
189 | _ => false, | ||
190 | } | ||
191 | } | ||
192 | } | ||
193 | ``` | ||
194 | |||
195 | - Split import | ||
196 | |||
197 | ```rust | ||
198 | // before: | ||
199 | use algo:<|>:visitor::{Visitor, visit}; | ||
200 | //after: | ||
201 | use algo::{<|>visitor::{Visitor, visit}}; | ||
202 | ``` | ||
203 | |||
204 | ## LSP features | ||
205 | |||
206 | * **Go to definition**: works correctly for local variables and some paths, | ||
207 | falls back to heuristic name matching for other things for the time being. | ||
208 | |||
209 | * **Completion**: completes paths, including dependencies and standard library. | ||
210 | Does not handle glob imports and macros. Completes fields and inherent | ||
211 | methods. | ||
212 | |||
213 | * **Outline** <kbd>alt+shift+o</kbd> | ||
214 | |||
215 | * **Signature Info** | ||
216 | |||
217 | * **Format document**. Formats the current file with rustfmt. Rustfmt must be | ||
218 | installed separately with `rustup component add rustfmt`. | ||
219 | |||
220 | * **Hover** shows types of expressions and docstings | ||
221 | |||
222 | * **Rename** works for local variables | ||
223 | |||
224 | * **Code Lens** for running tests | ||
225 | |||
226 | * **Folding** | ||
227 | |||
228 | * **Diagnostics** | ||
229 | - missing module for `mod foo;` with a fix to create `foo.rs`. | ||
230 | - struct field shorthand | ||
231 | - unnecessary braces in use item | ||
232 | |||
233 | |||
234 | ## Performance | ||
235 | |||
236 | Rust Analyzer is expected to be pretty fast. Specifically, the initial analysis | ||
237 | of the project (i.e, when you first invoke completion or symbols) typically | ||
238 | takes dozen of seconds at most. After that, everything is supposed to be more or | ||
239 | less instant. However currently all analysis results are kept in memory, so | ||
240 | memory usage is pretty high. Working with `rust-lang/rust` repo, for example, | ||
241 | needs about 5 gigabytes of ram. | ||