Rust Analyzer is just a usual rust project, which is organized as a Cargo workspace, builds on stable and doesn't depend on C libraries. So, just
$ cargo test
should be enough to get you started!
To learn more about how rust-analyzer works, see ./architecture.md document.
We also publish rustdoc docs to pages:
https://rust-analyzer.github.io/rust-analyzer/ra_ide/
Various organizational and process issues are discussed in this document.
Rust Analyzer is a part of RLS-2.0 working group. Discussion happens in this Zulip stream:
https://rust-lang.zulipchat.com/#narrow/stream/185405-t-compiler.2Fwg-rls-2.2E0
We have this "work list" paper document:
https://paper.dropbox.com/doc/RLS-2.0-work-list--AZ3BgHKKCtqszbsi3gi6sjchAQ-42vbnxzuKq2lKwW0mkn8Y
It shows what everyone is working on right now. If you want to (this is not mandatory), add yourself to the list!
- good-first-issue are good issues to get into the project.
- E-mentor issues have links to the code in question and tests.
- E-easy, E-medium, E-hard, labels are estimates for how hard would be to write a fix.
- fun is for cool, but probably hard stuff.
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 rule.
You can run cargo xtask install-pre-commit-hook
to install git-hook to run rustfmt on commit.
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 xtask
package. It contains
stuff like formatting checking, code generation and powers cargo xtask install
.
The latter syntax is achieved with the help of cargo aliases (see .cargo
directory).
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!).
I often just install development version with cargo xtask install --server --jemalloc
and
restart the host VS Code.
See ./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 :-)
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
.
Tests are located inside src/test
and are named *.test.ts
. They use the
Mocha test framework and the builtin Node
assert module. Unlike normal Node tests
they must be hosted inside a VS Code instance. This can be done in one of two
ways:
-
When
F5
debugging in VS Code select theExtension Tests
configuration from the drop-down at the top of the Debug View. This will launch a temporary instance of VS Code. The test results will appear in the "Debug Console" tab of the primary VS Code instance. -
Run
npm test
from the command line. Although this is initiated from the command line it is not headless; it will also launch a temporary instance of VS Code.
Due to the requirements of running the tests inside VS Code they are not run on CI. When making changes to the extension please ensure the tests are not broken locally before opening a Pull Request.
To install only the VS Code extension, use cargo xtask install --client-code
.
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
env_logger
for logging frontend. By default, log goes to stderr, but the
stderr itself is processed by VS Code.
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 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 xtask install --server --jemalloc
. -
Rust Analyzer: Syntax Tree
shows syntax tree of the current file/selection.
We have a built-in hierarchical profiler, you can enable it by using RA_PROF
env-var:
RA_PROFILE=* // dump everything
RA_PROFILE=foo|bar|baz // enabled only selected entries
RA_PROFILE=*@3>10 // dump everything, up to depth 3, if it takes more than 10 ms
In particular, I have `export RA_PROFILE='*>10' in my shell profile.
To measure time for from-scratch analysis, use something like this:
$ cargo run --release -p ra_cli -- analysis-stats ../chalk/
For measuring time of incremental analysis, use either of these:
$ cargo run --release -p ra_cli -- analysis-bench ../chalk/ --highlight ../chalk/chalk-engine/src/logic.rs
$ cargo run --release -p ra_cli -- analysis-bench ../chalk/ --complete ../chalk/chalk-engine/src/logic.rs:94:0