aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/dev/README.md81
-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
42be green as well. We use bors-ng to enforce the [not rocket 42be green as well. We use bors-ng to enforce the [not rocket
43science](https://graydon2.dreamwidth.org/1597.html) rule. 43science](https://graydon2.dreamwidth.org/1597.html) rule.
44
45You can run `cargo format-hook` to install git-hook to run rustfmt on commit.
46
47# Code organization
48
49All Rust code lives in the `crates` top-level directory, and is organized as a
50single Cargo workspace. The `editors` top-level directory contains code for
51integrating with editors. Currently, it contains plugins for VS Code (in
52typescript) and Emacs (in elisp). The `docs` top-level directory contains both
53developer and user documentation.
54
55We have some automation infra in Rust in the `crates/tool` package. It contains
56stuff like formatting checking, code generation and powers `cargo install-code`.
57The latter syntax is achieved with the help of cargo aliases (see `.cargo`
58directory).
59
60# Launching rust-analyzer
61
62Debugging language server can be tricky: LSP is rather chatty, so driving it
63from the command line is not really feasible, driving it via VS Code requires
64interacting with two processes.
65
66For this reason, the best way to see how rust-analyzer works is to find a
67relevant test and execute it (VS Code includes an action for running a single
68test).
69
70However, launching a VS Code instance with locally build language server is
71possible. There's even a VS Code task for this, so just <kbd>F5</kbd> should
72work (thanks, [@andrew-w-ross](https://github.com/andrew-w-ross)!).
73
74I often just install development version with `cargo jinstall-lsp` and
75restart the host VS Code.
76
77See [./debugging.md](./debugging.md) for how to attach to rust-analyzer with
78debugger, and don't forget that rust-analyzer has useful `pd` snippet and `dbg`
79postfix completion for printf debugging :-)
80
81# Working With VS Code Extension
82
83To work on the VS Code extension, launch code inside `editors/code` and use `F5`
84to launch/debug. To automatically apply formatter and linter suggestions, use
85`npm run fix`.
86
87# Logging
88
89Logging is done by both rust-analyzer and VS Code, so it might be tricky to
90figure out where logs go.
91
92Inside 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
94with `env_logger`), but the stderr itself is processed by VS Code. To mirror
95logs to a `./log` directory, set `RA_INTERNAL_MODE=1` environmental variable.
96
97To see stderr in the running VS Code instance, go to the "Output" tab of the
98panel 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
101To 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
114There'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!
7See also the [guide](./guide.md), which walks through a particular snapshot of 7See also the [guide](./guide.md), which walks through a particular snapshot of
8rust-analyzer code base. 8rust-analyzer code base.
9 9
10For syntax-trees specifically, there's a [video walk 10Yet another resource is this playlist with videos about various parts of the
11through](https://youtu.be/DGAuLWdCCAI) as well. 11analyzer:
12
13https://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
66Rust syntax tree structure and parser. See 68Rust 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
146An LSP implementation which wraps `ra_ide_api` into a langauge server protocol. 148An LSP implementation which wraps `ra_ide_api` into a langauge server protocol.
147 149
148### `crates/ra_vfs` 150### `ra_vfs`
149 151
150Although `hir` and `ra_ide_api` don't do any IO, we need to be able to read 152Although `hir` and `ra_ide_api` don't do any IO, we need to be able to read
151files from disk at the end of the day. This is what `ra_vfs` does. It also 153files from disk at the end of the day. This is what `ra_vfs` does. It also
152manages overlays: "dirty" files in the editor, whose "true" contents is 154manages overlays: "dirty" files in the editor, whose "true" contents is
153different from data on disk. 155different from data on disk. This is more or less the single really
156platform-dependent component, so it lives in a separate repository and has an
157extensive 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
165A CLI interface to rust-analyzer. 169A CLI interface to rust-analyzer.
166 170
167### `crate/tools`
168
169Custom 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
177VS Code plugin
178
179
180## Common workflows
181
182To 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
186To see logs from the language server, set `RUST_LOG=info` env variable. To see
187all 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
190There's `rust-analyzer: status` command which prints common high-level debug 172## Testing Infrastructure
191info. In particular, it prints info about memory usage of various data
192structures, 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
196To run tests, just `cargo test`.
197 174
198To work on the VS Code extension, launch code inside `editors/code` and use `F5` to
199launch/debug. To automatically apply formatter and linter suggestions, use `npm
200run 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