Merge #521
521: refresh docs r=matklad a=matklad Co-authored-by: Aleksey Kladov <aleksey.kladov@gmail.com>
This commit is contained in:
bors[bot]
commit
9f2072d45f
74
README.md
74
README.md
@ -2,15 +2,13 @@
|
||||
|
||||
[](https://travis-ci.org/rust-analyzer/rust-analyzer)
|
||||
|
||||
Rust Analyzer is an **experimental** modular compiler frontend for the
|
||||
Rust language, which aims to lay a foundation for excellent IDE
|
||||
support.
|
||||
Rust Analyzer is an **experimental** modular compiler frontend for the Rust
|
||||
language, which aims to lay a foundation for excellent IDE support.
|
||||
|
||||
It doesn't implement much of compiler functionality yet, but the
|
||||
white-space preserving Rust parser works, and there are significant
|
||||
chunks of overall architecture (indexing, on-demand & lazy
|
||||
computation, snapshotable world view) in place. Some basic IDE
|
||||
functionality is provided via a language server.
|
||||
It doesn't implement much of compiler functionality yet, but the white-space
|
||||
preserving Rust parser works, and there are significant chunks of overall
|
||||
architecture (indexing, on-demand & lazy computation, snapshotable world view)
|
||||
in place. Some basic IDE functionality is provided via a language server.
|
||||
|
||||
Work on the Rust Analyzer is sponsored by
|
||||
|
||||
@ -30,53 +28,45 @@ $ cargo run --package ra_cli parse < crates/ra_syntax/src/lib.rs
|
||||
|
||||
# show symbols of a Rust file
|
||||
$ cargo run --package ra_cli symbols < crates/ra_syntax/src/lib.rs
|
||||
|
||||
# install the language server
|
||||
$ cargo install --path crates/ra_lsp_server
|
||||
```
|
||||
|
||||
To try out the language server, see [these
|
||||
instructions](./editors/README.md). Please note that the server is not
|
||||
ready for general use yet. If you are looking for a Rust IDE that
|
||||
works, use [IntelliJ
|
||||
Rust](https://github.com/intellij-rust/intellij-rust) or
|
||||
[RLS](https://github.com/rust-lang-nursery/rls). That being said, the
|
||||
basic stuff works, and rust analyzer is developed in the rust analyzer
|
||||
powered editor.
|
||||
|
||||
See [these instructions](./editors/README.md) for VS Code setup and the list of
|
||||
features (some of which are VS Code specific).
|
||||
|
||||
## Current Status and Plans
|
||||
|
||||
Rust analyzer aims to fill the same niche as the official [Rust
|
||||
Language Server](https://github.com/rust-lang-nursery/rls), but uses a
|
||||
significantly different architecture. More details can be found [in
|
||||
this
|
||||
Rust analyzer aims to fill the same niche as the official [Rust Language
|
||||
Server](https://github.com/rust-lang-nursery/rls), but uses a significantly
|
||||
different architecture. More details can be found [in this
|
||||
thread](https://internals.rust-lang.org/t/2019-strategy-for-rustc-and-the-rls/8361),
|
||||
but the core issue is that RLS works in the "wait until user stops
|
||||
typing, run the build process, save the results of the analysis" mode,
|
||||
which arguably is the wrong foundation for IDE.
|
||||
but the core issue is that RLS works in the "wait until user stops typing, run
|
||||
the build process, save the results of the analysis" mode, which arguably is the
|
||||
wrong foundation for IDE.
|
||||
|
||||
Rust Analyzer is a hobby project at the moment, there's exactly zero
|
||||
Rust Analyzer is an experimental project at the moment, there's exactly zero
|
||||
guarantees that it becomes production-ready one day.
|
||||
|
||||
The near/mid term plan is to work independently of the main rustc
|
||||
compiler and implement at least simplistic versions of name
|
||||
resolution, macro expansion and type inference. The purpose is two
|
||||
fold:
|
||||
The near/mid term plan is to work independently of the main rustc compiler and
|
||||
implement at least simplistic versions of name resolution, macro expansion and
|
||||
type inference. The purpose is two fold:
|
||||
|
||||
* to quickly bootstrap usable and useful language server: solution
|
||||
that covers 80% of Rust code will be useful for IDEs, and will be
|
||||
vastly simpler than 100% solution.
|
||||
* to quickly bootstrap usable and useful language server: solution that covers
|
||||
80% of Rust code will be useful for IDEs, and will be vastly simpler than 100%
|
||||
solution.
|
||||
|
||||
* to understand how the consumer-side of compiler API should look like
|
||||
(especially it's on-demand aspects). If you have
|
||||
`get_expression_type` function, you can write a ton of purely-IDE
|
||||
features on top of it, even if the function is only partially
|
||||
correct. Plugin in the precise function afterwards should just make
|
||||
IDE features more reliable.
|
||||
(especially it's on-demand aspects). If you have `get_expression_type`
|
||||
function, you can write a ton of purely-IDE features on top of it, even if the
|
||||
function is only partially correct. Pluging in the precise function afterwards
|
||||
should just make IDE features more reliable.
|
||||
|
||||
The long term plan is to merge with the mainline rustc compiler,
|
||||
probably around the HIR boundary? That is, use rust analyzer for
|
||||
parsing, macro expansion and related bits of name resolution, but
|
||||
leave the rest (including type inference and trait selection) to the
|
||||
existing rustc.
|
||||
The long term plan is to merge with the mainline rustc compiler, probably around
|
||||
the HIR boundary? That is, use rust analyzer for parsing, macro expansion and
|
||||
related bits of name resolution, but leave the rest (including type inference
|
||||
and trait selection) to the existing rustc.
|
||||
|
||||
## Getting in touch
|
||||
|
||||
|
||||
@ -4,72 +4,96 @@ To install experimental VS Code plugin:
|
||||
$ git clone https://github.com/rust-analyzer/rust-analyzer.git --depth 1
|
||||
$ cd rust-analyzer
|
||||
$ cargo install-code
|
||||
|
||||
# for stdlib support
|
||||
$ rustup component add rust-src
|
||||
```
|
||||
|
||||
This will run `cargo install --packge ra_lsp_server` to install the
|
||||
server binary into `~/.cargo/bin`, and then will build and install
|
||||
plugin from `editors/code`. See
|
||||
[this](https://github.com/matklad/rust-analyzer/blob/cc76b0d31d8ba013c499dd3a4ca69b37004795e6/crates/tools/src/main.rs#L192)
|
||||
for details
|
||||
This will run `cargo install --packge ra_lsp_server` to install the server
|
||||
binary into `~/.cargo/bin`, and then will build and install plugin from
|
||||
`editors/code`. See
|
||||
[this](https://github.com/rust-analyzer/rust-analyzer/blob/0199572a3d06ff66eeae85a2d2c9762996f0d2d8/crates/tools/src/main.rs#L150)
|
||||
for details. The installation is expected to *just work*, if it doesn't, report
|
||||
bugs!
|
||||
|
||||
It's better to remove existing Rust plugins to avoid interference.
|
||||
|
||||
### Features:
|
||||
## Rust Analyzer Specifc Features
|
||||
|
||||
* syntax highlighting (LSP does not have API for it, so impl is hacky
|
||||
and sometimes fall-backs to the horrible built-in highlighting)
|
||||
These features are implemented as extensions to the langauge server protocol.
|
||||
They are more experimental in nature and work only with VS Code.
|
||||
|
||||
* **Go to symbol in workspace** (`ctrl+t`)
|
||||
- `#Foo` searches for `Foo` type in the current workspace
|
||||
- `#foo#` searches for `foo` function in the current workspace
|
||||
- `#Foo*` searches for `Foo` type among dependencies, excluding `stdlib`
|
||||
- Sorry for a weired UI, neither LSP, not VSCode have any sane API for filtering! :)
|
||||
### Syntax highlighting
|
||||
|
||||
* **Go to symbol in file** (`alt+shift+o`)
|
||||
It overrides built-in highlighting, and works only with a specific theme
|
||||
(zenburn). `ra-lsp.highlightingOn` setting can be used to disable it.
|
||||
|
||||
* **Go to definition** ("correct" for `mod foo;` decls, approximate for other things).
|
||||
### Go to symbol in workspace <kbd>ctrl+t</kbd>
|
||||
|
||||
* commands (`ctrl+shift+p` or keybindings)
|
||||
- **Show Rust Syntax Tree** (use it to verify that plugin works)
|
||||
- **Rust Extend Selection**. Extends the current selection to the
|
||||
encompassing syntactic construct (expression, statement, item,
|
||||
module, etc). It works with multiple cursors. Do bind this command
|
||||
to a key, its super-useful!
|
||||
- **Rust Matching Brace**. If the cursor is on any brace
|
||||
(`<>(){}[]`) which is a part of a brace-pair, moves cursor to the
|
||||
matching brace.
|
||||
- **Rust Parent Module**. Navigate to the parent module of the current module
|
||||
- **Rust Join Lines**. Join selected lines into one, smartly fixing
|
||||
up whitespace and trailing commas.
|
||||
- **Run test at caret**. When cursor is inside a function marked
|
||||
`#[test]`, this action runs this specific test. If the cursor is
|
||||
outside of the test function, this re-runs the last test. Do bind
|
||||
this to a shortcut!
|
||||
- **Format document**. Formats the current file with rustfmt.
|
||||
Rustfmt must be installed separately with `rustup component add rustfmt`.
|
||||
It mostly works on top of the built-in LSP functionality, however `#` and `*`
|
||||
symbols can be used to narrow down the search. Specifically,
|
||||
|
||||
* Typing assists
|
||||
- typing `let =` tries to smartly add `;` if `=` is followed by an existing expression.
|
||||
- Enter inside comments continues comment (`<|>` signifies cursor position):
|
||||
- `#Foo` searches for `Foo` type in the current workspace
|
||||
- `#foo#` searches for `foo` function in the current workspace
|
||||
- `#Foo*` searches for `Foo` type among dependencies, excluding `stdlib`
|
||||
- `#foo#*` seaches for `foo` function among dependencies.
|
||||
|
||||
```
|
||||
/// Docs<|>
|
||||
fn foo() {}
|
||||
```
|
||||
That is, `#` switches from "types" to all symbols, `*` switches from the current
|
||||
workspace to dependencies.
|
||||
|
||||
```
|
||||
/// Docs
|
||||
/// <|>
|
||||
fn foo() {}
|
||||
```
|
||||
### Commands <kbd>ctrl+shift+p</kbd>
|
||||
|
||||
* code actions (use `ctrl+.` to activate).
|
||||
#### Show Rust Syntax Tree
|
||||
|
||||
Shows the parse tree of the current file. It exists mostly for debugging
|
||||
rust-analyzer itself.
|
||||
|
||||
#### Extend Selection
|
||||
|
||||
Extends the current selection to the encompassing syntactic construct
|
||||
(expression, statement, item, module, etc). It works with multiple cursors. Do
|
||||
bind this command to a key, its super-useful! Expected to be upstreamed to LSP soonish:
|
||||
https://github.com/Microsoft/language-server-protocol/issues/613
|
||||
|
||||
#### Matching Brace
|
||||
|
||||
If the cursor is on any brace (`<>(){}[]`) which is a part of a brace-pair,
|
||||
moves cursor to the matching brace. It uses the actual parser to determine
|
||||
braces, so it won't confuse generics with comparisons.
|
||||
|
||||
#### Parent Module
|
||||
|
||||
Navigates to the parent module of the current module.
|
||||
|
||||
#### Join Lines
|
||||
|
||||
Join selected lines into one, smartly fixing up whitespace and trailing commas.
|
||||
|
||||
#### Run
|
||||
|
||||
Shows popup suggesting to run a test/benchmark/binary **at the current cursor
|
||||
location**. Super useful for repeatedly running just a single test. Do bind this
|
||||
to a shortcut!
|
||||
|
||||
|
||||
### On Typing Assists
|
||||
|
||||
Some features trigger on typing certain characters:
|
||||
|
||||
- typing `let =` tries to smartly add `;` if `=` is followed by an existing expression.
|
||||
- Enter inside comments automatically inserts `///`
|
||||
- typing `.` in a chain method call auto-indents
|
||||
|
||||
|
||||
### Code Actions (Assists)
|
||||
|
||||
These are triggered in a particular context via lightbulb. We use custom code on
|
||||
the VS Code side to be able to position cursor.
|
||||
|
||||
|
||||
- Flip `,`
|
||||
|
||||
```
|
||||
```rust
|
||||
// before:
|
||||
fn foo(x: usize,<|> dim: (usize, usize))
|
||||
// after:
|
||||
@ -78,7 +102,7 @@ fn foo(dim: (usize, usize), x: usize)
|
||||
|
||||
- Add `#[derive]`
|
||||
|
||||
```
|
||||
```rust
|
||||
// before:
|
||||
struct Foo {
|
||||
<|>x: i32
|
||||
@ -92,7 +116,7 @@ struct Foo {
|
||||
|
||||
- Add `impl`
|
||||
|
||||
```
|
||||
```rust
|
||||
// before:
|
||||
struct Foo<'a, T: Debug> {
|
||||
<|>t: T
|
||||
@ -106,3 +130,90 @@ impl<'a, T: Debug> Foo<'a, T> {
|
||||
<|>
|
||||
}
|
||||
```
|
||||
|
||||
- Change visibility
|
||||
|
||||
```rust
|
||||
// before:
|
||||
fn<|> foo() {}
|
||||
|
||||
// after
|
||||
pub(crate) fn foo() {}
|
||||
```
|
||||
|
||||
- Introduce variable:
|
||||
|
||||
```rust
|
||||
// before:
|
||||
fn foo() {
|
||||
foo(<|>1 + 1<|>);
|
||||
}
|
||||
|
||||
// after:
|
||||
fn foo() {
|
||||
let var_name = 1 + 1;
|
||||
foo(var_name);
|
||||
}
|
||||
```
|
||||
|
||||
- Replace if-let with match:
|
||||
|
||||
```rust
|
||||
// before:
|
||||
impl VariantData {
|
||||
pub fn is_struct(&self) -> bool {
|
||||
if <|>let VariantData::Struct(..) = *self {
|
||||
true
|
||||
} else {
|
||||
false
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// after:
|
||||
impl VariantData {
|
||||
pub fn is_struct(&self) -> bool {
|
||||
<|>match *self {
|
||||
VariantData::Struct(..) => true,
|
||||
_ => false,
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- Split import
|
||||
|
||||
```rust
|
||||
// before:
|
||||
use algo:<|>:visitor::{Visitor, visit};
|
||||
//after:
|
||||
use algo::{<|>visitor::{Visitor, visit}};
|
||||
```
|
||||
|
||||
## LSP features
|
||||
|
||||
* **Go to definition**: works correctly for local variables and some paths,
|
||||
falls back to heuristic name matching for other things for the time being.
|
||||
|
||||
* **Completion**: completes paths, including dependencies and standard library.
|
||||
Does not handle glob imports and macros. Completes fields and inherent methods
|
||||
|
||||
* **Outline** <kbd>alt+shift+o</kbd>
|
||||
|
||||
* **Signature Info**
|
||||
|
||||
* **Format document**. Formats the current file with rustfmt. Rustfmt must be
|
||||
installed separately with `rustup component add rustfmt`.
|
||||
|
||||
* **Hover** shows types of expressions and docstings
|
||||
|
||||
* **Rename** works for local variables
|
||||
|
||||
* **Code Lens** for running tests
|
||||
|
||||
* **Folding**
|
||||
|
||||
* **Diagnostics**
|
||||
- missing module for `mod foo;` with a fix to create `foo.rs`.
|
||||
- struct field shorthand
|
||||
- unnessary braces in use item
|
||||
|
||||
Loading…
Reference in New Issue
Block a user