diff options
-rw-r--r-- | docs/dev/README.md | 81 | ||||
-rw-r--r-- | docs/dev/architecture.md (renamed from docs/dev/arhictecture.md) | 46 | ||||
-rw-r--r-- | docs/dev/debugging.md (renamed from docs/dev/DEBUGGING.md) | 0 |
3 files changed, 91 insertions, 36 deletions
diff --git a/docs/dev/README.md b/docs/dev/README.md index 0c09dddfc..ac7f4fd71 100644 --- a/docs/dev/README.md +++ b/docs/dev/README.md | |||
@@ -41,3 +41,84 @@ 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 | 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 | 42 | be green as well. We use bors-ng to enforce the [not rocket |
43 | science](https://graydon2.dreamwidth.org/1597.html) rule. | 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/docs/dev/arhictecture.md b/docs/dev/architecture.md index 57f76ebae..3cd63bf73 100644 --- a/docs/dev/arhictecture.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,7 @@ 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 | |||
179 | |||
180 | ## Common workflows | ||
181 | |||
182 | To try out VS Code extensions, run `cargo install-code`. This installs both the | ||
183 | `ra_lsp_server` binary and the VS Code extension. To install only the binary, use | ||
184 | `cargo install-lsp` (shorthand for `cargo install --path crates/ra_lsp_server --force`) | ||
185 | |||
186 | To see logs from the language server, set `RUST_LOG=info` env variable. To see | ||
187 | all communication between the server and the client, use | ||
188 | `RUST_LOG=gen_lsp_server=debug` (this will print quite a bit of stuff). | ||
189 | 171 | ||
190 | There's `rust-analyzer: status` command which prints common high-level debug | 172 | ## Testing Infrastructure |
191 | info. In particular, it prints info about memory usage of various data | ||
192 | structures, and, if compiled with jemalloc support (`cargo jinstall-lsp` or | ||
193 | `cargo install --path crates/ra_lsp_server --force --features jemalloc`), includes | ||
194 | statistic about the heap. | ||
195 | 173 | ||
196 | To run tests, just `cargo test`. | ||
197 | 174 | ||
198 | To work on the VS Code extension, launch code inside `editors/code` and use `F5` to | ||
199 | launch/debug. To automatically apply formatter and linter suggestions, use `npm | ||
200 | run fix`. | ||
diff --git a/docs/dev/DEBUGGING.md b/docs/dev/debugging.md index f868e6998..f868e6998 100644 --- a/docs/dev/DEBUGGING.md +++ b/docs/dev/debugging.md | |||