aboutsummaryrefslogtreecommitdiff
path: root/ARCHITECTURE.md
diff options
context:
space:
mode:
Diffstat (limited to 'ARCHITECTURE.md')
-rw-r--r--ARCHITECTURE.md57
1 files changed, 31 insertions, 26 deletions
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 277b29c12..9c404f4c3 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -15,7 +15,7 @@ More specifically, input data consists of a set of test files (`(PathBuf,
15String)` pairs) and an information about project structure, the so called 15String)` pairs) and an information about project structure, the so called
16`CrateGraph`. Crate graph specifies which files are crate roots, which cfg flags 16`CrateGraph`. Crate graph specifies which files are crate roots, which cfg flags
17are specified for each crate (TODO: actually implement this) and what are 17are specified for each crate (TODO: actually implement this) and what are
18dependencies between the crate. The analyzer keeps all these input data in 18dependencies between the crates. The analyzer keeps all these input data in
19memory and never does any IO. Because the input data is source code, which 19memory and never does any IO. Because the input data is source code, which
20typically measures in tens of megabytes at most, keeping all input data in 20typically measures in tens of megabytes at most, keeping all input data in
21memory is OK. 21memory is OK.
@@ -74,9 +74,9 @@ notes.
74- `algo`: generic tree algorithms, including `walk` for O(1) stack 74- `algo`: generic tree algorithms, including `walk` for O(1) stack
75 space tree traversal (this is cool) and `visit` for type-driven 75 space tree traversal (this is cool) and `visit` for type-driven
76 visiting the nodes (this is double plus cool, if you understand how 76 visiting the nodes (this is double plus cool, if you understand how
77 `Visitor` works, you understand rust-analyzer). 77 `Visitor` works, you understand the design of syntax trees).
78 78
79Test for ra_syntax are mostly data-driven: `tests/data/parser` contains a bunch of `.rs` 79Tests for ra_syntax are mostly data-driven: `tests/data/parser` contains a bunch of `.rs`
80(test vectors) and `.txt` files with corresponding syntax trees. During testing, we check 80(test vectors) and `.txt` files with corresponding syntax trees. During testing, we check
81`.rs` against `.txt`. If the `.txt` file is missing, it is created (this is how you update 81`.rs` against `.txt`. If the `.txt` file is missing, it is created (this is how you update
82tests). Additionally, running `cargo gen-tests` will walk the grammar module and collect 82tests). Additionally, running `cargo gen-tests` will walk the grammar module and collect
@@ -107,41 +107,46 @@ guessing a HIR for a particular source position.
107 107
108Underneath, HIR works on top of salsa, using a `HirDatabase` trait. 108Underneath, HIR works on top of salsa, using a `HirDatabase` trait.
109 109
110### `crates/ra_analysis` 110### `crates/ra_ide_api`
111 111
112A stateful library for analyzing many Rust files as they change. 112A stateful library for analyzing many Rust files as they change. `AnalysisHost`
113`AnalysisHost` is a mutable entity (clojure's atom) which holds the 113is a mutable entity (clojure's atom) which holds the current state, incorporates
114current state, incorporates changes and handles out `Analysis` --- an 114changes and handles out `Analysis` --- an immutable and consistent snapshot of
115immutable and consistent snapshot of world state at a point in time, which 115world state at a point in time, which actually powers analysis.
116actually powers analysis.
117 116
118One interesting aspect of analysis is its support for cancellation. When a change 117One interesting aspect of analysis is its support for cancellation. When a
119is applied to `AnalysisHost`, first all currently active snapshots are 118change is applied to `AnalysisHost`, first all currently active snapshots are
120cancelled. Only after all snapshots are dropped the change actually affects the 119cancelled. Only after all snapshots are dropped the change actually affects the
121database. 120database.
122 121
123### `crates/ra_lsp_server` 122APIs in this crate are IDE centric: they take text offsets as input and produce
124 123offsets and strings as output. This works on top of rich code model powered by
125An LSP implementation which uses `ra_analysis` for managing state and 124`hir`.
126`ra_editor` for actually doing useful stuff.
127
128See [#79](https://github.com/rust-analyzer/rust-analyzer/pull/79/) as an
129example of PR which adds a new feature to `ra_editor` and exposes it
130to `ra_lsp_server`.
131 125
132### `crates/ra_editor` 126### `crates/ra_ide_api_light`
133 127
134All IDE features which can be implemented if you only have access to a 128All IDE features which can be implemented if you only have access to a single
135single file. `ra_editor` could be used to enhance editing of Rust code 129file. `ra_ide_api_light` could be used to enhance editing of Rust code without
136without the need to fiddle with build-systems, file 130the need to fiddle with build-systems, file synchronization and such.
137synchronization and such.
138 131
139In a sense, `ra_editor` is just a bunch of pure functions which take a 132In a sense, `ra_ide_api_light` is just a bunch of pure functions which take a
140syntax tree as input. 133syntax tree as input.
141 134
142The tests for `ra_editor` are `#[cfg(test)] mod tests` unit-tests spread 135The tests for `ra_ide_api_light` are `#[cfg(test)] mod tests` unit-tests spread
143throughout its modules. 136throughout its modules.
144 137
138
139### `crates/ra_lsp_server`
140
141An LSP implementation which wraps `ra_ide_api` into a langauge server protocol.
142
143### `crates/ra_vfs`
144
145Although `hir` and `ra_ide_api` don't do any io, we need to be able to read
146files from disk at the end of the day. This is what `ra_vfs` does. It also
147manages overlays: "dirty" files in the editor, whose "true" contents is
148different from data on disk.
149
145### `crates/gen_lsp_server` 150### `crates/gen_lsp_server`
146 151
147A language server scaffold, exposing a synchronous crossbeam-channel based API. 152A language server scaffold, exposing a synchronous crossbeam-channel based API.