ARCHITECTURE.md

   1 # Architecture
   2
   3 This document describes high-level architecture of rust-analyzer.
   4 If you want to familiarize yourself with the code base, you are just
   5 in the right place!
   6
   7
   8 ## Code generation
   9
  10 Some of the components of this repository are generated through automatic
  11 processes. 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
  33 Rust syntax tree structure and parser. See
  34 [RFC](https://github.com/rust-lang/rfcs/pull/2256) for some design
  35 notes.
  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
  52 Test 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
  55 tests). Additionally, running `cargo gen-tests` will walk the grammar module and collect
  56 all `//test test_name` comments into files inside `tests/data` directory.
  57
  58 See [#93](https://github.com/rust-analyzer/rust-analyzer/pull/93) for an example PR which
  59 fixes a bug in the grammar.
  60
  61
  62 ### `crates/ra_editor`
  63
  64 All IDE features which can be implemented if you only have access to a
  65 single file. `ra_editor` could be used to enhance editing of Rust code
  66 without the need to fiddle with build-systems, file
  67 synchronization and such.
  68
  69 In a sense, `ra_editor` is just a bunch of pure functions which take a
  70 syntax tree as an input.
  71
  72 The tests for `ra_editor` are `#[cfg(test)] mod tests` unit-tests spread
  73 throughout its modules.
  74
  75 ### `crates/salsa`
  76
  77 An implementation of red-green incremental compilation algorithm from
  78 rust compiler. It makes all rust-analyzer features on-demand. To be replaced
  79 with `salsa-rs/salsa` soon.
  80
  81
  82 ### `crates/ra_analysis`
  83
  84 A stateful library for analyzing many Rust files as they change.
  85 `AnalysisHost` is a mutable entity (clojure's atom) which holds
  86 current state, incorporates changes and handles out `Analysis` --- an
  87 immutable consistent snapshot of world state at a point in time, which
  88 actually powers analysis.
  89
  90
  91 ### `crates/ra_lsp_server`
  92
  93 An LSP implementation which uses `ra_analysis` for managing state and
  94 `ra_editor` for actually doing useful stuff.
  95
  96 See [#79](https://github.com/rust-analyzer/rust-analyzer/pull/79/) as an
  97 example of PR which adds a new feature to `ra_editor` and exposes it
  98 to `ra_lsp_server`.
  99
 100
 101 ### `crates/cli`
 102
 103 A CLI interface to rust-analyzer.
 104
 105 ### `crate/tools`
 106
 107 Custom 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
 115 VS Code plugin
 116
 117
 118 ## Common workflows
 119
 120 To 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
 122 cargo install --path crates/ra_lsp_server --force`
 123
 124 To see logs from the language server, set `RUST_LOG=info` env variable. To see
 125 all communication between the server and the client, use
 126 `RUST_LOG=gen_lsp_server=debug` (will print quite a bit of stuff).
 127
 128 To run tests, just `cargo test`.
 129
 130 To work on VS Code extension, launch code inside `editors/code` and use `F5` to
 131 launch/debug. To automatically apply formatter and linter suggestions, use `npm
 132 run fix`.
 133