More information for mbe

[rust.git] / docs / dev / architecture.md

diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md
index 56ebaa3df0eb516f448aba8633655ac094cd4795..c5e4acea31e3659b7b3bb4b5f66d573932bf6a3a 100644 (file)
--- a/docs/dev/architecture.md
+++ b/docs/dev/architecture.md
@@ -75,7 +75,7 @@ Original [libsyntax parser](https://github.com/rust-lang/rust/blob/6b99adeb11313
 
 **Architecture Invariant:** the parser is independent of the particular tree structure and particular representation of the tokens.
 It transforms one flat stream of events into another flat stream of events.
-Token independence allows us to pares out both text-based source code and `tt`-based macro input.
+Token independence allows us to parse out both text-based source code and `tt`-based macro input.
 Tree independence allows us to more easily vary the syntax tree implementation.
 It should also unlock efficient light-parsing approaches.
 For example, you can extract the set of names defined in a file (for typo correction) without building a syntax tree.
@@ -254,6 +254,22 @@ A single `rust-analyzer` process can serve many projects, so it is important tha
 These crates implement macros as token tree -> token tree transforms.
 They are independent from the rest of the code.
 
+`tt` crate defined `TokenTree`, a single token or a delimited sequence of token trees.
+`mbe` crate contains tools for transforming between syntax trees and token tree.
+And it also handles the actual parsing and expansion of declarative macro (a-la "Macros By Example" or mbe).
+
+For proc macros, the client-server model are used to run proc-macro.
+We pass an argument `--proc-macro` to `rust-analyzer` binary to start a separate process  (`proc_macro_srv`).
+And the client (`proc_macro_api`) provides an interface to talk to that server separately.
+
+And then token trees are passed from client, and the server will load the corresponding dynamic library (which built by `cargo`).
+And due to the fact the api for getting result from proc macro are always unstable in `rustc`,
+we maintain our own copy (and paste) of that part of code to allow us to build the whole thing in stable rust.
+ 
+ **Architecture Invariant:**
+Bad proc macros may panic or segfault accidentally. So we run it in another process and recover it from fatal error.
+And they may be non-deterministic which conflict how `salsa` works, so special attention is required.
+
 ### `crates/cfg`
 
 This crate is responsible for parsing, evaluation and general definition of `cfg` attributes.