diff options
author | Kevin DeLorey <[email protected]> | 2020-02-09 16:25:47 +0000 |
---|---|---|
committer | Kevin DeLorey <[email protected]> | 2020-02-09 16:37:43 +0000 |
commit | a957c473fdb79880c39b73dc9e0c923093cf16ac (patch) | |
tree | f998b548f530ce604651e0e6af314ed2ec74b3b5 /docs/dev/README.md | |
parent | 22caf982b99c54058e2e9200aeea0e61cada284a (diff) | |
parent | 1b9b13b4b4a75b5531c3f046ce6bf72d681f2732 (diff) |
Merge branch 'master' into kdelorey/complete-trait-impl
Diffstat (limited to 'docs/dev/README.md')
-rw-r--r-- | docs/dev/README.md | 94 |
1 files changed, 43 insertions, 51 deletions
diff --git a/docs/dev/README.md b/docs/dev/README.md index 2f6215d6b..732e4bdd3 100644 --- a/docs/dev/README.md +++ b/docs/dev/README.md | |||
@@ -26,15 +26,6 @@ Discussion happens in this Zulip stream: | |||
26 | 26 | ||
27 | https://rust-lang.zulipchat.com/#narrow/stream/185405-t-compiler.2Fwg-rls-2.2E0 | 27 | https://rust-lang.zulipchat.com/#narrow/stream/185405-t-compiler.2Fwg-rls-2.2E0 |
28 | 28 | ||
29 | # Work List | ||
30 | |||
31 | We have this "work list" paper document: | ||
32 | |||
33 | https://paper.dropbox.com/doc/RLS-2.0-work-list--AZ3BgHKKCtqszbsi3gi6sjchAQ-42vbnxzuKq2lKwW0mkn8Y | ||
34 | |||
35 | It shows what everyone is working on right now. If you want to (this is not | ||
36 | mandatory), add yourself to the list! | ||
37 | |||
38 | # Issue Labels | 29 | # Issue Labels |
39 | 30 | ||
40 | * [good-first-issue](https://github.com/rust-analyzer/rust-analyzer/labels/good%20first%20issue) | 31 | * [good-first-issue](https://github.com/rust-analyzer/rust-analyzer/labels/good%20first%20issue) |
@@ -50,10 +41,12 @@ mandatory), add yourself to the list! | |||
50 | 41 | ||
51 | # CI | 42 | # CI |
52 | 43 | ||
53 | We use Travis for CI. Most of the things, including formatting, are checked by | 44 | 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 | 45 | `cargo test` so, if `cargo test` passes locally, that's a good sign that CI will |
55 | be green as well. We use bors-ng to enforce the [not rocket | 46 | be green as well. The only exception is that some long-running tests are skipped locally by default. |
56 | science](https://graydon2.dreamwidth.org/1597.html) rule. | 47 | Use `env RUN_SLOW_TESTS=1 cargo test` to run the full suite. |
48 | |||
49 | We use bors-ng to enforce the [not rocket science](https://graydon2.dreamwidth.org/1597.html) rule. | ||
57 | 50 | ||
58 | You can run `cargo xtask install-pre-commit-hook` to install git-hook to run rustfmt on commit. | 51 | You can run `cargo xtask install-pre-commit-hook` to install git-hook to run rustfmt on commit. |
59 | 52 | ||
@@ -61,9 +54,9 @@ You can run `cargo xtask install-pre-commit-hook` to install git-hook to run rus | |||
61 | 54 | ||
62 | All Rust code lives in the `crates` top-level directory, and is organized as a | 55 | All Rust code lives in the `crates` top-level directory, and is organized as a |
63 | single Cargo workspace. The `editors` top-level directory contains code for | 56 | single Cargo workspace. The `editors` top-level directory contains code for |
64 | integrating with editors. Currently, it contains plugins for VS Code (in | 57 | integrating with editors. Currently, it contains the plugin for VS Code (in |
65 | typescript) and Emacs (in elisp). The `docs` top-level directory contains both | 58 | typescript). The `docs` top-level directory contains both developer and user |
66 | developer and user documentation. | 59 | documentation. |
67 | 60 | ||
68 | We have some automation infra in Rust in the `xtask` package. It contains | 61 | We have some automation infra in Rust in the `xtask` package. It contains |
69 | stuff like formatting checking, code generation and powers `cargo xtask install`. | 62 | stuff like formatting checking, code generation and powers `cargo xtask install`. |
@@ -81,42 +74,41 @@ relevant test and execute it (VS Code includes an action for running a single | |||
81 | test). | 74 | test). |
82 | 75 | ||
83 | However, launching a VS Code instance with locally build language server is | 76 | However, launching a VS Code instance with locally build language server is |
84 | possible. There's even a VS Code task for this, so just <kbd>F5</kbd> should | 77 | possible. There's "Run Extension (Dev Server)" launch configuration for this. |
85 | work (thanks, [@andrew-w-ross](https://github.com/andrew-w-ross)!). | 78 | |
86 | 79 | In general, I use one of the following workflows for fixing bugs and | |
87 | I often just install development version with `cargo xtask install --server --jemalloc` and | 80 | implementing features. |
88 | restart the host VS Code. | 81 | |
89 | 82 | If the problem concerns only internal parts of rust-analyzer (ie, I don't need | |
90 | See [./debugging.md](./debugging.md) for how to attach to rust-analyzer with | 83 | to touch `ra_lsp_server` crate or typescript code), there is a unit-test for it. |
91 | debugger, and don't forget that rust-analyzer has useful `pd` snippet and `dbg` | 84 | So, I use **Rust Analyzer: Run** action in VS Code to run this single test, and |
92 | postfix completion for printf debugging :-) | 85 | then just do printf-driven development/debugging. As a sanity check after I'm |
93 | 86 | done, I use `cargo xtask install --server` and **Reload Window** action in VS | |
94 | # Working With VS Code Extension | 87 | Code to sanity check that the thing works as I expect. |
95 | 88 | ||
96 | To work on the VS Code extension, launch code inside `editors/code` and use `F5` | 89 | If the problem concerns only the VS Code extension, I use **Run Extension** |
97 | to launch/debug. To automatically apply formatter and linter suggestions, use | 90 | launch configuration from `launch.json`. Notably, this uses the usual |
98 | `npm run fix`. | 91 | `ra_lsp_server` binary from `PATH`. After I am done with the fix, I use `cargo |
99 | 92 | xtask install --client-code` to try the new extension for real. | |
100 | Tests are located inside `src/test` and are named `*.test.ts`. They use the | 93 | |
101 | [Mocha](https://mochajs.org) test framework and the builtin Node | 94 | If I need to fix something in the `ra_lsp_server` crate, I feel sad because it's |
102 | [assert](https://nodejs.org/api/assert.html) module. Unlike normal Node tests | 95 | on the boundary between the two processes, and working there is slow. I usually |
103 | they must be hosted inside a VS Code instance. This can be done in one of two | 96 | just `cargo xtask install --server` and poke changes from my live environment. |
104 | ways: | 97 | Note that this uses `--release`, which is usually faster overall, because |
105 | 98 | loading stdlib into debug version of rust-analyzer takes a lot of time. To speed | |
106 | 1. When `F5` debugging in VS Code select the `Extension Tests` configuration | 99 | things up, sometimes I open a temporary hello-world project which has |
107 | from the drop-down at the top of the Debug View. This will launch a temporary | 100 | `"rust-analyzer.withSysroot": false` in `.code/settings.json`. This flag causes |
108 | instance of VS Code. The test results will appear in the "Debug Console" tab | 101 | rust-analyzer to skip loading the sysroot, which greatly reduces the amount of |
109 | of the primary VS Code instance. | 102 | things rust-analyzer needs to do, and makes printf's more useful. Note that you |
110 | 103 | should only use `eprint!` family of macros for debugging: stdout is used for LSP | |
111 | 2. Run `npm test` from the command line. Although this is initiated from the | 104 | communication, and `print!` would break it. |
112 | command line it is not headless; it will also launch a temporary instance of | 105 | |
113 | VS Code. | 106 | If I need to fix something simultaneously in the server and in the client, I |
114 | 107 | feel even more sad. I don't have a specific workflow for this case. | |
115 | Due to the requirements of running the tests inside VS Code they are **not run | 108 | |
116 | on CI**. When making changes to the extension please ensure the tests are not | 109 | Additionally, I use `cargo run --release -p ra_cli -- analysis-stats |
117 | broken locally before opening a Pull Request. | 110 | path/to/some/rust/crate` to run a batch analysis. This is primarily useful for |
118 | 111 | performance optimizations, or for bug minimization. | |
119 | To install **only** the VS Code extension, use `cargo xtask install --client-code`. | ||
120 | 112 | ||
121 | # Logging | 113 | # Logging |
122 | 114 | ||