1 # Contributing Quick Start
3 Rust Analyzer is an ordinary Rust project, which is organized as a Cargo
4 workspace, builds on stable and doesn't depend on C libraries. So, just
10 should be enough to get you started!
12 To learn more about how rust-analyzer works, see
13 [./architecture.md](./architecture.md) document.
15 We also publish rustdoc docs to pages:
17 https://rust-analyzer.github.io/rust-analyzer/ide/
19 Various organizational and process issues are discussed in this document.
23 Rust Analyzer is a part of [RLS-2.0 working
24 group](https://github.com/rust-lang/compiler-team/tree/6a769c13656c0a6959ebc09e7b1f7c09b86fb9c0/working-groups/rls-2.0).
25 Discussion happens in this Zulip stream:
27 https://rust-lang.zulipchat.com/#narrow/stream/185405-t-compiler.2Fwg-rls-2.2E0
31 * [good-first-issue](https://github.com/rust-analyzer/rust-analyzer/labels/good%20first%20issue)
32 are good issues to get into the project.
33 * [E-has-instructions](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-has-instructions)
34 issues have links to the code in question and tests.
35 * [E-easy](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy),
36 [E-medium](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-medium),
37 [E-hard](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-hard),
38 [E-unknown](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-unknown),
39 labels are *estimates* for how hard would be to write a fix. Each triaged issue should have one of these labels.
40 * [S-actionable](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AS-actionable) and
41 [S-unactionable](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AS-unactionable)
42 specify if there are concrete steps to resolve or advance an issue. Roughly, actionable issues need only work to be fixed,
43 while unactionable ones are effectively wont-fix. Each triaged issue should have one of these labels.
44 * [fun](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3Afun)
45 is for cool, but probably hard stuff.
46 * [Design](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%Design)
47 is for moderate/large scale architecture discussion.
49 These issues should generally include a link to a Zulip discussion thread.
53 We use GitHub Actions for CI. Most of the things, including formatting, are checked by
54 `cargo test` so, if `cargo test` passes locally, that's a good sign that CI will
55 be green as well. The only exception is that some long-running tests are skipped locally by default.
56 Use `env RUN_SLOW_TESTS=1 cargo test` to run the full suite.
58 We use bors-ng to enforce the [not rocket science](https://graydon2.dreamwidth.org/1597.html) rule.
60 You can run `cargo xtask install-pre-commit-hook` to install git-hook to run rustfmt on commit.
62 # Launching rust-analyzer
64 Debugging the language server can be tricky.
65 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.
67 For this reason, the best way to see how rust-analyzer works is to find a relevant test and execute it.
68 VS Code & Emacs include an action for running a single test.
70 Launching a VS Code instance with a locally built language server is also possible.
71 There's **"Run Extension (Debug Build)"** launch configuration for this in VS Code.
73 In general, I use one of the following workflows for fixing bugs and implementing features:
75 If the problem concerns only internal parts of rust-analyzer (i.e. I don't need to touch the `rust-analyzer` crate or TypeScript code), there is a unit-test for it.
76 So, I use **Rust Analyzer: Run** action in VS Code to run this single test, and then just do printf-driven development/debugging.
77 As a sanity check after I'm done, I use `cargo xtask install --server` and **Reload Window** action in VS Code to verify that the thing works as I expect.
79 If the problem concerns only the VS Code extension, I use **Run Installed Extension** launch configuration from `launch.json`.
80 Notably, this uses the usual `rust-analyzer` binary from `PATH`.
81 For this, it is important to have the following in your `settings.json` file:
84 "rust-analyzer.server.path": "rust-analyzer"
87 After I am done with the fix, I use `cargo xtask install --client` to try the new extension for real.
89 If I need to fix something in the `rust-analyzer` crate, I feel sad because it's on the boundary between the two processes, and working there is slow.
90 I usually just `cargo xtask install --server` and poke changes from my live environment.
91 Note that this uses `--release`, which is usually faster overall, because loading stdlib into debug version of rust-analyzer takes a lot of time.
92 To speed things up, sometimes I open a temporary hello-world project which has `"rust-analyzer.withSysroot": false` in `.code/settings.json`.
93 This flag causes rust-analyzer to skip loading the sysroot, which greatly reduces the amount of things rust-analyzer needs to do, and makes printf's more useful.
94 Note that you should only use the `eprint!` family of macros for debugging: stdout is used for LSP communication, and `print!` would break it.
96 If I need to fix something simultaneously in the server and in the client, I feel even more sad.
97 I don't have a specific workflow for this case.
99 Additionally, I use `cargo run --release -p rust-analyzer -- analysis-stats path/to/some/rust/crate` to run a batch analysis.
100 This is primarily useful for performance optimizations, or for bug minimization.
104 Tests for the parser (`parser`) live in the `syntax` crate (see `test_data` directory).
105 There are two kinds of tests:
107 * Manually written test cases in `parser/ok` and `parser/err`
108 * "Inline" tests in `parser/inline` (these are generated) from comments in `parser` crate.
110 The purpose of inline tests is not to achieve full coverage by test cases, but to explain to the reader of the code what each particular `if` and `match` is responsible for.
111 If you are tempted to add a large inline test, it might be a good idea to leave only the simplest example in place, and move the test to a manual `parser/ok` test.
113 To update test data, run with `UPDATE_EXPECT` variable:
116 env UPDATE_EXPECT=1 cargo qt
119 After adding a new inline test you need to run `cargo xtest codegen` and also update the test data as described above.
123 If you change files under `editors/code` and would like to run the tests and linter, install npm and run:
133 All Rust code lives in the `crates` top-level directory, and is organized as a single Cargo workspace.
134 The `editors` top-level directory contains code for integrating with editors.
135 Currently, it contains the plugin for VS Code (in TypeScript).
136 The `docs` top-level directory contains both developer and user documentation.
138 We have some automation infra in Rust in the `xtask` package.
139 It contains stuff like formatting checking, code generation and powers `cargo xtask install`.
140 The latter syntax is achieved with the help of cargo aliases (see `.cargo` directory).
142 # Architecture Invariants
144 This section tries to document high-level design constraints, which are not
145 always obvious from the low-level code.
147 ## Incomplete syntax trees
149 Syntax trees are by design incomplete and do not enforce well-formedness.
150 If an AST method returns an `Option`, it *can* be `None` at runtime, even if this is forbidden by the grammar.
154 rust-analyzer is independent from LSP.
155 It provides features for a hypothetical perfect Rust-specific IDE client.
156 Internal representations are lowered to LSP in the `rust-analyzer` crate (the only crate which is allowed to use LSP types).
158 ## IDE/Compiler split
160 There's a semi-hard split between "compiler" and "IDE", at the `hir` crate.
161 Compiler derives new facts about source code.
162 It explicitly acknowledges that not all info is available (i.e. you can't look at types during name resolution).
164 IDE assumes that all information is available at all times.
166 IDE should use only types from `hir`, and should not depend on the underling compiler types.
171 The main IDE crate (`ide`) uses "Plain Old Data" for the API.
172 Rather than talking in definitions and references, it talks in Strings and textual offsets.
173 In general, API is centered around UI concerns -- the result of the call is what the user sees in the editor, and not what the compiler sees underneath.
174 The results are 100% Rust specific though.
175 Shout outs to LSP developers for popularizing the idea that "UI" is a good place to draw a boundary at.
179 The protocol is implemented in the mostly stateless way.
180 A good mental model is HTTP, which doesn't store per-client state, and instead relies on devices like cookies to maintain an illusion of state.
181 If some action requires multi-step protocol, each step should be self-contained.
183 A good example here is code action resolving process.
184 TO display the lightbulb, we compute the list of code actions without computing edits.
185 Figuring out the edit is done in a separate `codeAction/resolve` call.
186 Rather than storing some `lazy_edit: Box<dyn FnOnce() -> Edit>` somewhere, we use a string ID of action to re-compute the list of actions during the resolve process.
187 (See [this post](https://rust-analyzer.github.io/blog/2020/09/28/how-to-make-a-light-bulb.html) for more details.)
188 The benefit here is that, generally speaking, the state of the world might change between `codeAction` and `codeAction` resolve requests, so any closure we store might become invalid.
190 While we don't currently implement any complicated refactors with complex GUI, I imagine we'd use the same techniques for refactors.
191 After clicking each "Next" button during refactor, the client would send all the info which server needs to re-recreate the context from scratch.
195 CI does not test rust-analyzer, CI is a core part of rust-analyzer, and is maintained with above average standard of quality.
196 CI is reproducible -- it can only be broken by changes to files in this repository, any dependence on externalities is a bug.
198 # Code Style & Review Process
200 Do see [./style.md](./style.md).
204 Logging is done by both rust-analyzer and VS Code, so it might be tricky to
205 figure out where logs go.
207 Inside rust-analyzer, we use the standard `log` crate for logging, and
208 `env_logger` for logging frontend. By default, log goes to stderr, but the
209 stderr itself is processed by VS Code.
211 To see stderr in the running VS Code instance, go to the "Output" tab of the
212 panel and select `rust-analyzer`. This shows `eprintln!` as well. Note that
213 `stdout` is used for the actual protocol, so `println!` will break things.
215 To log all communication between the server and the client, there are two choices:
217 * you can log on the server side, by running something like
219 env RA_LOG=lsp_server=debug code .
222 * you can log on the client side, by enabling `"rust-analyzer.trace.server":
223 "verbose"` workspace setting. These logs are shown in a separate tab in the
224 output and could be used with LSP inspector. Kudos to
225 [@DJMcNab](https://github.com/DJMcNab) for setting this awesome infra up!
228 There are also two VS Code commands which might be of interest:
230 * `Rust Analyzer: Status` shows some memory-usage statistics.
232 * `Rust Analyzer: Syntax Tree` shows syntax tree of the current file/selection.
234 * `Rust Analyzer: View Hir` shows the HIR expressions within the function containing the cursor.
236 You can hover over syntax nodes in the opened text file to see the appropriate
237 rust code that it refers to and the rust editor will also highlight the proper
240 If you trigger Go to Definition in the inspected Rust source file,
241 the syntax tree read-only editor should scroll to and select the
242 appropriate syntax node token.
244 ![demo](https://user-images.githubusercontent.com/36276403/78225773-6636a480-74d3-11ea-9d9f-1c9d42da03b0.png)
248 We have a built-in hierarchical profiler, you can enable it by using `RA_PROFILE` env-var:
251 RA_PROFILE=* // dump everything
252 RA_PROFILE=foo|bar|baz // enabled only selected entries
253 RA_PROFILE=*@3>10 // dump everything, up to depth 3, if it takes more than 10 ms
256 In particular, I have `export RA_PROFILE='*>10'` in my shell profile.
258 We also have a "counting" profiler which counts number of instances of popular structs.
259 It is enabled by `RA_COUNT=1`.
261 To measure time for from-scratch analysis, use something like this:
264 $ cargo run --release -p rust-analyzer -- analysis-stats ../chalk/
267 For measuring time of incremental analysis, use either of these:
270 $ cargo run --release -p rust-analyzer -- analysis-bench ../chalk/ --highlight ../chalk/chalk-engine/src/logic.rs
271 $ cargo run --release -p rust-analyzer -- analysis-bench ../chalk/ --complete ../chalk/chalk-engine/src/logic.rs:94:0
276 Release process is handled by `release`, `dist` and `promote` xtasks, `release` being the main one.
278 `release` assumes that you have checkouts of `rust-analyzer`, `rust-analyzer.github.io`, and `rust-lang/rust` in the same directory:
282 ./rust-analyzer.github.io
283 ./rust-rust-analyzer # Note the name!
286 Additionally, it assumes that remote for `rust-analyzer` is called `upstream` (I use `origin` to point to my fork).
290 1. Inside rust-analyzer, run `cargo xtask release`. This will:
291 * checkout the `release` branch
292 * reset it to `upstream/nightly`
293 * push it to `upstream`. This triggers GitHub Actions which:
294 * runs `cargo xtask dist` to package binaries and VS Code extension
295 * makes a GitHub release
296 * pushes VS Code extension to the marketplace
297 * create new changelog in `rust-analyzer.github.io`
298 * create `rust-analyzer.github.io/git.log` file with the log of merge commits since last release
299 2. While the release is in progress, fill-in the changelog using `git.log`
300 3. Commit & push the changelog
302 5. Inside `rust-analyzer`, run `cargo xtask promote` -- this will create a PR to rust-lang/rust updating rust-analyzer's submodule.
305 If the GitHub Actions release fails because of a transient problem like a timeout, you can re-run the job from the Actions console.
306 If it fails because of something that needs to be fixed, remove the release tag (if needed), fix the problem, then start over.
307 Make sure to remove the new changelog post created when running `cargo xtask release` a second time.
311 There are three sets of people with extra permissions:
313 * rust-analyzer GitHub organization **admins** (which include current t-compiler leads).
314 Admins have full access to the org.
315 * **review** team in the organization.
316 Reviewers have `r+` access to all of organization's repositories and publish rights on crates.io.
317 They also have direct commit access, but all changes should via bors queue.
318 It's ok to self-approve if you think you know what you are doing!
319 bors should automatically sync the permissions.
320 * **triage** team in the organization.
321 This team can label and close issues.