aboutsummaryrefslogtreecommitdiff
path: root/ARCHITECTURE.md
diff options
context:
space:
mode:
Diffstat (limited to 'ARCHITECTURE.md')
-rw-r--r--ARCHITECTURE.md133
1 files changed, 133 insertions, 0 deletions
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 000000000..b497cc5d7
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,133 @@
1# Architecture
2
3This document describes high-level architecture of rust-analyzer.
4If you want to familiarize yourself with the code base, you are just
5in the right place!
6
7
8## Code generation
9
10Some of the components of this repository are generated through automatic
11processes. These are outlined below:
12
13- `gen-kinds`: The kinds of tokens are reused in several places, so a generator
14 is used. We use tera templates to generate the files listed below, based on
15 the grammar described in [grammar.ron]:
16 - [ast/generated.rs][ast generated] in `ra_syntax` based on
17 [ast/generated.tera.rs][ast source]
18 - [syntax_kinds/generated.rs][syntax_kinds generated] in `ra_syntax` based on
19 [syntax_kinds/generated.tera.rs][syntax_kinds source]
20
21[tera]: https://tera.netlify.com/
22[grammar.ron]: ./crates/ra_syntax/src/grammar.ron
23[ast generated]: ./crates/ra_syntax/src/ast/generated.rs
24[ast source]: ./crates/ra_syntax/src/ast/generated.rs.tera
25[syntax_kinds generated]: ./crates/ra_syntax/src/syntax_kinds/generated.rs
26[syntax_kinds source]: ./crates/ra_syntax/src/syntax_kinds/generated.rs.tera
27
28
29## Code Walk-Through
30
31### `crates/ra_syntax`
32
33Rust syntax tree structure and parser. See
34[RFC](https://github.com/rust-lang/rfcs/pull/2256) for some design
35notes.
36
37- [rowan](https://github.com/rust-analyzer/rowan) library is used for constructing syntax trees.
38- `grammar` module is the actual parser. It is a hand-written recursive descent parsers, which
39 produces a sequence of events like "start node X", "finish not Y". It works similarly to [kotlin parser](https://github.com/JetBrains/kotlin/blob/4d951de616b20feca92f3e9cc9679b2de9e65195/compiler/frontend/src/org/jetbrains/kotlin/parsing/KotlinParsing.java),
40 which is a good source for inspiration for dealing with syntax errors and incomplete input. Original [libsyntax parser](https://github.com/rust-lang/rust/blob/6b99adeb11313197f409b4f7c4083c2ceca8a4fe/src/libsyntax/parse/parser.rs)
41 is what we use for the definition of the Rust language.
42- `parser_api/parser_impl` bridges the tree-agnostic parser from `grammar` with `rowan` trees.
43 This is the thing that turns a flat list of events into a tree (see `EventProcessor`)
44- `ast` a type safe API on top of the raw `rowan` tree.
45- `grammar.ron` RON description of the grammar, which is used to
46 generate `syntax_kinds` and `ast` modules, using `cargo gen-kinds` command.
47- `algo`: generic tree algorithms, including `walk` for O(1) stack
48 space tree traversal (this is cool) and `visit` for type-driven
49 visiting the nodes (this is double plus cool, if you understand how
50 `Visitor` works, you understand rust-analyzer).
51
52Test for ra_syntax are mostly data-driven: `tests/data/parser` contains a bunch of `.rs`
53(test vectors) and `.txt` files with corresponding syntax trees. During testing, we check
54`.rs` against `.txt`. If the `.txt` file is missing, it is created (this is how you update
55tests). Additionally, running `cargo gen-tests` will walk the grammar module and collect
56all `//test test_name` comments into files inside `tests/data` directory.
57
58See [#93](https://github.com/rust-analyzer/rust-analyzer/pull/93) for an example PR which
59fixes a bug in the grammar.
60
61
62### `crates/ra_editor`
63
64All IDE features which can be implemented if you only have access to a
65single file. `ra_editor` could be used to enhance editing of Rust code
66without the need to fiddle with build-systems, file
67synchronization and such.
68
69In a sense, `ra_editor` is just a bunch of pure functions which take a
70syntax tree as an input.
71
72The tests for `ra_editor` are `#[cfg(test)] mod tests` unit-tests spread
73throughout its modules.
74
75### `crates/salsa`
76
77An implementation of red-green incremental compilation algorithm from
78rust compiler. It makes all rust-analyzer features on-demand. To be replaced
79with `salsa-rs/salsa` soon.
80
81
82### `crates/ra_analysis`
83
84A stateful library for analyzing many Rust files as they change.
85`AnalysisHost` is a mutable entity (clojure's atom) which holds
86current state, incorporates changes and handles out `Analysis` --- an
87immutable consistent snapshot of world state at a point in time, which
88actually powers analysis.
89
90
91### `crates/ra_lsp_server`
92
93An LSP implementation which uses `ra_analysis` for managing state and
94`ra_editor` for actually doing useful stuff.
95
96See [#79](https://github.com/rust-analyzer/rust-analyzer/pull/79/) as an
97example of PR which adds a new feature to `ra_editor` and exposes it
98to `ra_lsp_server`.
99
100
101### `crates/cli`
102
103A CLI interface to rust-analyzer.
104
105### `crate/tools`
106
107Custom Cargo tasks used to develop rust-analyzer:
108
109- `cargo gen-kinds` -- generate `ast` and `syntax_kinds`
110- `cargo gen-tests` -- collect inline tests from grammar
111- `cargo install-code` -- build and install VS Code extension and server
112
113### `editors/code`
114
115VS Code plugin
116
117
118## Common workflows
119
120To try out VS Code extensions, run `cargo install-code`. This installs both the
121`ra_lsp_server` binary and VS Code extension. To install only the binary, `use
122cargo install --path crates/ra_lsp_server --force`
123
124To see logs from the language server, set `RUST_LOG=info` env variable. To see
125all communication between the server and the client, use
126`RUST_LOG=gen_lsp_server=debug` (will print quite a bit of stuff).
127
128To run tests, just `cargo test`.
129
130To work on VS Code extension, launch code inside `editors/code` and use `F5` to
131launch/debug. To automatically apply formatter and linter suggestions, use `npm
132run fix`.
133