diff --git a/docs/dev/README.md b/docs/dev/README.md index 0c09dddfc96..ac7f4fd71bf 100644 --- a/docs/dev/README.md +++ b/docs/dev/README.md @@ -41,3 +41,84 @@ We use Travis for CI. Most of the things, including formatting, are checked by `cargo test` so, if `cargo test` passes locally, that's a good sign that CI will be green as well. We use bors-ng to enforce the [not rocket science](https://graydon2.dreamwidth.org/1597.html) rule. + +You can run `cargo format-hook` to install git-hook to run rustfmt on commit. + +# Code organization + +All Rust code lives in the `crates` top-level directory, and is organized as a +single Cargo workspace. The `editors` top-level directory contains code for +integrating with editors. Currently, it contains plugins for VS Code (in +typescript) and Emacs (in elisp). The `docs` top-level directory contains both +developer and user documentation. + +We have some automation infra in Rust in the `crates/tool` package. It contains +stuff like formatting checking, code generation and powers `cargo install-code`. +The latter syntax is achieved with the help of cargo aliases (see `.cargo` +directory). + +# Launching rust-analyzer + +Debugging language server can be tricky: LSP is rather chatty, so driving it +from the command line is not really feasible, driving it via VS Code requires +interacting with two processes. + +For this reason, the best way to see how rust-analyzer works is to find a +relevant test and execute it (VS Code includes an action for running a single +test). + +However, launching a VS Code instance with locally build language server is +possible. There's even a VS Code task for this, so just F5 should +work (thanks, [@andrew-w-ross](https://github.com/andrew-w-ross)!). + +I often just install development version with `cargo jinstall-lsp` and +restart the host VS Code. + +See [./debugging.md](./debugging.md) for how to attach to rust-analyzer with +debugger, and don't forget that rust-analyzer has useful `pd` snippet and `dbg` +postfix completion for printf debugging :-) + +# Working With VS Code Extension + +To work on the VS Code extension, launch code inside `editors/code` and use `F5` +to launch/debug. To automatically apply formatter and linter suggestions, use +`npm run fix`. + +# Logging + +Logging is done by both rust-analyzer and VS Code, so it might be tricky to +figure out where logs go. + +Inside rust-analyzer, we use the standard `log` crate for logging, and +`flexi_logger` for logging frotend. By default, log goes to stderr (the same as +with `env_logger`), but the stderr itself is processed by VS Code. To mirror +logs to a `./log` directory, set `RA_INTERNAL_MODE=1` environmental variable. + +To see stderr in the running VS Code instance, go to the "Output" tab of the +panel and select `rust-analyzer`. This shows `eprintln!` as well. Note that +`stdout` is used for the actual protocol, so `println!` will break things. + +To log all communication between the server and the client, there are two choices: + +* you can log on the server side, by running something like + ``` + env RUST_LOG=gen_lsp_server=trace code . + ``` + +* you can log on the client side, by enabling `"rust-analyzer.trace.server": + "verbose"` workspace setting. These logs are shown in a separate tab in the + output and could be used with LSP inspector. Kudos to + [@DJMcNab](https://github.com/DJMcNab) for setting this awesome infra up! + + +There's also two VS Code commands which might be of interest: + +* `Rust Analyzer: Status` shows some memory-usage statistics. To take full + advantage of it, you need to compile rust-analyzer with jemalloc support: + ``` + $ cargo install --path crates/ra_lsp_server --force --features jemalloc + ``` + + There's an alias for this: `cargo jinstall-lsp`. + +* `Rust Analyzer: Syntax Tree` shows syntax tree of the current file/selection. diff --git a/docs/dev/arhictecture.md b/docs/dev/architecture.md similarity index 83% rename from docs/dev/arhictecture.md rename to docs/dev/architecture.md index 57f76ebaecf..3cd63bf732a 100644 --- a/docs/dev/arhictecture.md +++ b/docs/dev/architecture.md @@ -7,8 +7,10 @@ in the right place! See also the [guide](./guide.md), which walks through a particular snapshot of rust-analyzer code base. -For syntax-trees specifically, there's a [video walk -through](https://youtu.be/DGAuLWdCCAI) as well. +Yet another resource is this playlist with videos about various parts of the +analyzer: + +https://www.youtube.com/playlist?list=PL85XCvVPmGQho7MZkdW-wtPtuJcFpzycE ## The Big Picture @@ -61,7 +63,7 @@ processes. These are outlined below: ## Code Walk-Through -### `crates/ra_syntax` +### `crates/ra_syntax`, `crates/ra_parser` Rust syntax tree structure and parser. See [RFC](https://github.com/rust-lang/rfcs/pull/2256) for some design notes. @@ -145,12 +147,14 @@ throughout its modules. An LSP implementation which wraps `ra_ide_api` into a langauge server protocol. -### `crates/ra_vfs` +### `ra_vfs` Although `hir` and `ra_ide_api` don't do any IO, we need to be able to read files from disk at the end of the day. This is what `ra_vfs` does. It also manages overlays: "dirty" files in the editor, whose "true" contents is -different from data on disk. +different from data on disk. This is more or less the single really +platform-dependent component, so it lives in a separate repository and has an +extensive cross-platform CI testing. ### `crates/gen_lsp_server` @@ -164,37 +168,7 @@ Run with `RUST_LOG=sync_lsp_server=debug` to see all the messages. A CLI interface to rust-analyzer. -### `crate/tools` -Custom Cargo tasks used to develop rust-analyzer: - -- `cargo gen-syntax` -- generate `ast` and `syntax_kinds` -- `cargo gen-tests` -- collect inline tests from grammar -- `cargo install-code` -- build and install VS Code extension and server - -### `editors/code` - -VS Code plugin +## Testing Infrastructure -## Common workflows - -To try out VS Code extensions, run `cargo install-code`. This installs both the -`ra_lsp_server` binary and the VS Code extension. To install only the binary, use -`cargo install-lsp` (shorthand for `cargo install --path crates/ra_lsp_server --force`) - -To see logs from the language server, set `RUST_LOG=info` env variable. To see -all communication between the server and the client, use -`RUST_LOG=gen_lsp_server=debug` (this will print quite a bit of stuff). - -There's `rust-analyzer: status` command which prints common high-level debug -info. In particular, it prints info about memory usage of various data -structures, and, if compiled with jemalloc support (`cargo jinstall-lsp` or -`cargo install --path crates/ra_lsp_server --force --features jemalloc`), includes - statistic about the heap. - -To run tests, just `cargo test`. - -To work on the VS Code extension, launch code inside `editors/code` and use `F5` to -launch/debug. To automatically apply formatter and linter suggestions, use `npm -run fix`. diff --git a/docs/dev/DEBUGGING.md b/docs/dev/debugging.md similarity index 100% rename from docs/dev/DEBUGGING.md rename to docs/dev/debugging.md