Skip to content

Commit 22f189b

Browse files
committed
Auto merge of rust-lang#16228 - Veykril:arch.md, r=Veykril
minor: Add some more crates to architecture.md
2 parents 306defa + 16457ab commit 22f189b

File tree

1 file changed

+35
-16
lines changed

1 file changed

+35
-16
lines changed

docs/dev/architecture.md

Lines changed: 35 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -134,29 +134,29 @@ This is to enable parallel parsing of all files.
134134
**Architecture Invariant:** Syntax trees are by design incomplete and do not enforce well-formedness.
135135
If an AST method returns an `Option`, it *can* be `None` at runtime, even if this is forbidden by the grammar.
136136

137-
### `crates/base_db`
137+
### `crates/base-db`
138138

139139
We use the [salsa](https://github.com/salsa-rs/salsa) crate for incremental and on-demand computation.
140140
Roughly, you can think of salsa as a key-value store, but it can also compute derived values using specified functions.
141-
The `base_db` crate provides basic infrastructure for interacting with salsa.
141+
The `base-db` crate provides basic infrastructure for interacting with salsa.
142142
Crucially, it defines most of the "input" queries: facts supplied by the client of the analyzer.
143143
Reading the docs of the `base_db::input` module should be useful: everything else is strictly derived from those inputs.
144144

145145
**Architecture Invariant:** particularities of the build system are *not* the part of the ground state.
146-
In particular, `base_db` knows nothing about cargo.
146+
In particular, `base-db` knows nothing about cargo.
147147
For example, `cfg` flags are a part of `base_db`, but `feature`s are not.
148148
A `foo` feature is a Cargo-level concept, which is lowered by Cargo to `--cfg feature=foo` argument on the command line.
149149
The `CrateGraph` structure is used to represent the dependencies between the crates abstractly.
150150

151-
**Architecture Invariant:** `base_db` doesn't know about file system and file paths.
151+
**Architecture Invariant:** `base-db` doesn't know about file system and file paths.
152152
Files are represented with opaque `FileId`, there's no operation to get an `std::path::Path` out of the `FileId`.
153153

154-
### `crates/hir_expand`, `crates/hir_def`, `crates/hir_ty`
154+
### `crates/hir-expand`, `crates/hir-def`, `crates/hir_ty`
155155

156156
These crates are the *brain* of rust-analyzer.
157157
This is the compiler part of the IDE.
158158

159-
`hir_xxx` crates have a strong [ECS](https://en.wikipedia.org/wiki/Entity_component_system) flavor, in that they work with raw ids and directly query the database.
159+
`hir-xxx` crates have a strong [ECS](https://en.wikipedia.org/wiki/Entity_component_system) flavor, in that they work with raw ids and directly query the database.
160160
There's little abstraction here.
161161
These crates integrate deeply with salsa and chalk.
162162

@@ -186,7 +186,7 @@ If you think about "using rust-analyzer as a library", `hir` crate is most likel
186186
It wraps ECS-style internal API into a more OO-flavored API (with an extra `db` argument for each call).
187187

188188
**Architecture Invariant:** `hir` provides a static, fully resolved view of the code.
189-
While internal `hir_*` crates _compute_ things, `hir`, from the outside, looks like an inert data structure.
189+
While internal `hir-*` crates _compute_ things, `hir`, from the outside, looks like an inert data structure.
190190

191191
`hir` also handles the delicate task of going from syntax to the corresponding `hir`.
192192
Remember that the mapping here is one-to-many.
@@ -200,7 +200,7 @@ Then we look for our node in the set of children.
200200
This is the heart of many IDE features, like goto definition, which start with figuring out the hir node at the cursor.
201201
This is some kind of (yet unnamed) uber-IDE pattern, as it is present in Roslyn and Kotlin as well.
202202

203-
### `crates/ide`
203+
### `crates/ide`, `crates/ide-db`, `crates/ide-assists`, `crates/ide-completion`, `crates/ide-diagnostics`, `crates/ide-ssr`
204204

205205
The `ide` crate builds on top of `hir` semantic model to provide high-level IDE features like completion or goto definition.
206206
It is an **API Boundary**.
@@ -217,8 +217,8 @@ Shout outs to LSP developers for popularizing the idea that "UI" is a good place
217217
`AnalysisHost` is a state to which you can transactionally `apply_change`.
218218
`Analysis` is an immutable snapshot of the state.
219219

220-
Internally, `ide` is split across several crates. `ide_assists`, `ide_completion` and `ide_ssr` implement large isolated features.
221-
`ide_db` implements common IDE functionality (notably, reference search is implemented here).
220+
Internally, `ide` is split across several crates. `ide-assists`, `ide-completion`, `ide-diagnostics` and `ide-ssr` implement large isolated features.
221+
`ide-db` implements common IDE functionality (notably, reference search is implemented here).
222222
The `ide` contains a public API/façade, as well as implementation for a plethora of smaller features.
223223

224224
**Architecture Invariant:** `ide` crate strives to provide a _perfect_ API.
@@ -251,14 +251,14 @@ This is a tricky business.
251251
**Architecture Invariant:** `rust-analyzer` should be partially available even when the build is broken.
252252
Reloading process should not prevent IDE features from working.
253253

254-
### `crates/toolchain`, `crates/project_model`, `crates/flycheck`
254+
### `crates/toolchain`, `crates/project-model`, `crates/flycheck`
255255

256256
These crates deal with invoking `cargo` to learn about project structure and get compiler errors for the "check on save" feature.
257257

258-
They use `crates/path` heavily instead of `std::path`.
258+
They use `crates/paths` heavily instead of `std::path`.
259259
A single `rust-analyzer` process can serve many projects, so it is important that server's current directory does not leak.
260260

261-
### `crates/mbe`, `crates/tt`, `crates/proc_macro_api`, `crates/proc_macro_srv`
261+
### `crates/mbe`, `crates/tt`, `crates/proc-macro-api`, `crates/proc-macro-srv`, `crates/proc-macro-srv-cli`
262262

263263
These crates implement macros as token tree -> token tree transforms.
264264
They are independent from the rest of the code.
@@ -268,8 +268,8 @@ They are independent from the rest of the code.
268268
And it also handles the actual parsing and expansion of declarative macro (a-la "Macros By Example" or mbe).
269269

270270
For proc macros, the client-server model are used.
271-
We start a separate process (`proc_macro_srv`) which loads and runs the proc-macros for us.
272-
And the client (`proc_macro_api`) provides an interface to talk to that server separately.
271+
We start a separate process (`proc-macro-srv-cli`) which loads and runs the proc-macros for us.
272+
And the client (`proc-macro-api`) provides an interface to talk to that server separately.
273273

274274
And then token trees are passed from client, and the server will load the corresponding dynamic library (which built by `cargo`).
275275
And due to the fact the api for getting result from proc macro are always unstable in `rustc`,
@@ -283,7 +283,7 @@ And they may be non-deterministic which conflict how `salsa` works, so special a
283283

284284
This crate is responsible for parsing, evaluation and general definition of `cfg` attributes.
285285

286-
### `crates/vfs`, `crates/vfs-notify`
286+
### `crates/vfs`, `crates/vfs-notify`, `crates/paths`
287287

288288
These crates implement a virtual file system.
289289
They provide consistent snapshots of the underlying file system and insulate messy OS paths.
@@ -301,6 +301,25 @@ as copies of unstable std items we would like to make use of already, like `std:
301301

302302
This crate contains utilities for CPU and memory profiling.
303303

304+
### `crates/intern`
305+
306+
This crate contains infrastructure for globally interning things via `Arc`.
307+
308+
### `crates/load-cargo`
309+
310+
This crate exposes several utilities for loading projects, used by the main `rust-analyzer` crate
311+
and other downstream consumers.
312+
313+
### `crates/rustc-dependencies`
314+
315+
This crate wraps the `rustc_*` crates rust-analyzer relies on and conditionally points them to
316+
mirrored crates-io releases such that rust-analyzer keeps building on stable.
317+
318+
### `crates/span`
319+
320+
This crate exposes types and functions related to rust-analyzer's span for macros.
321+
322+
A span is effectively a text range relative to some item in a file with a given `SyntaxContext` (hygiene).
304323

305324
## Cross-Cutting Concerns
306325

0 commit comments

Comments
 (0)