aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAleksey Kladov <[email protected]>2018-09-16 13:36:09 +0100
committerAleksey Kladov <[email protected]>2018-09-16 13:36:09 +0100
commitb5cb53ea93f2573b76515a0b651eeb13bb5a74f0 (patch)
tree193a7f6125a281a46093049148c0dc1b6a00cece
parentcc76b0d31d8ba013c499dd3a4ca69b37004795e6 (diff)
tweak readme
-rw-r--r--README.md103
-rw-r--r--editors/README.md89
2 files changed, 135 insertions, 57 deletions
diff --git a/README.md b/README.md
index 41fc8bbba..9504e433d 100644
--- a/README.md
+++ b/README.md
@@ -16,54 +16,28 @@ functionality is provided via a language server.
16 16
17## Quick Start 17## Quick Start
18 18
19Rust analyzer builds on stable Rust >= 1.29.0.
20
19``` 21```
22# run tests
20$ cargo test 23$ cargo test
21$ cargo parse < crates/libsyntax2/src/lib.rs
22```
23 24
24## Trying It Out 25# show syntax tree of a Rust file
26$ cargo run --package ra_cli parse < crates/ra_syntax/src/lib.rs
25 27
26This installs experimental VS Code plugin 28# show symbols of a Rust file
27 29$ cargo run --package ra_cli symbols < crates/ra_syntax/src/lib.rs
28```
29$ cargo install-code
30``` 30```
31 31
32It's better to remove existing Rust plugins to avoid interference. 32To try out the language server, see [these
33Warning: plugin is not intended for general use, has a lot of rough 33instructions](./editors/README.md). Please note that the server is not
34edges and missing features (notably, no code completion). That said, 34ready for general use yet. If you are looking for a Rust IDE that
35while originally libsyntax2 was developed in IntelliJ, @matklad now 35works, use [IntelliJ
36uses this plugin (and thus, libsytax2) to develop libsyntax2, and it 36Rust](https://github.com/intellij-rust/intellij-rust) or
37doesn't hurt too much :-) 37[RLS](https://github.com/rust-lang-nursery/rls). That being said, the
38 38basic stuff works, and rust analyzer is developed in the rust analyzer
39 39powered editor.
40### Features:
41
42* syntax highlighting (LSP does not have API for it, so impl is hacky
43 and sometimes fall-backs to the horrible built-in highlighting)
44
45* commands (`ctrl+shift+p` or keybindings)
46 - **Show Rust Syntax Tree** (use it to verify that plugin works)
47 - **Rust Extend Selection** (works with multiple cursors)
48 - **Rust Matching Brace** (knows the difference between `<` and `<`)
49 - **Rust Parent Module**
50 - **Rust Join Lines** (deals with trailing commas)
51 40
52* **Go to symbol in file**
53
54* **Go to symbol in workspace**
55 - `#Foo` searches for `Foo` type in the current workspace
56 - `#foo#` searches for `foo` function in the current workspace
57 - `#Foo*` searches for `Foo` type among dependencies, excluding `stdlib`
58 - Sorry for a weired UI, neither LSP, not VSCode have any sane API for filtering! :)
59
60* code actions:
61 - Flip `,` in comma separated lists
62 - Add `#[derive]` to struct/enum
63 - Add `impl` block to struct/enum
64 - Run tests at caret
65
66* **Go to definition** ("correct" for `mod foo;` decls, index-based for functions).
67 41
68## Current Status and Plans 42## Current Status and Plans
69 43
@@ -104,7 +78,11 @@ existing rustc.
104 78
105## Code Walk-Through 79## Code Walk-Through
106 80
107### `crates/libsyntax2` 81### `crates/ra_syntax`
82
83Rust syntax tree structure and parser. See
84[RFC](https://github.com/rust-lang/rfcs/pull/2256) for some design
85notes.
108 86
109- `yellow`, red/green syntax tree, heavily inspired [by this](https://github.com/apple/swift/tree/ab68f0d4cbf99cdfa672f8ffe18e433fddc8b371/lib/Syntax) 87- `yellow`, red/green syntax tree, heavily inspired [by this](https://github.com/apple/swift/tree/ab68f0d4cbf99cdfa672f8ffe18e433fddc8b371/lib/Syntax)
110- `grammar`, the actual parser 88- `grammar`, the actual parser
@@ -117,24 +95,35 @@ existing rustc.
117 `Visitor` works, you understand libsyntax2). 95 `Visitor` works, you understand libsyntax2).
118 96
119 97
120### `crates/libeditor` 98### `crates/ra_editor`
99
100All IDE features which can be implemented if you only have access to a
101single file. `ra_editor` could be used to enhance editing of Rust code
102without the need to fiddle with build-systems, file
103synchronization and such.
104
105In a sense, `ra_editor` is just a bunch of pure functions which take a
106syntax tree as an input.
107
108### `crates/salsa`
121 109
122Most of IDE features leave here, unlike `libanalysis`, `libeditor` is 110An implementation of red-green incremental compilation algorithm from
123single-file and is basically a bunch of pure functions. 111rust compiler. It makes all rust-analyzer features on-demand.
124 112
125 113
126### `crates/libanalysis` 114### `crates/ra_analysis`
127 115
128A stateful library for analyzing many Rust files as they change. 116A stateful library for analyzing many Rust files as they change.
129`WorldState` is a mutable entity (clojure's atom) which holds current 117`AnalysisHost` is a mutable entity (clojure's atom) which holds
130state, incorporates changes and handles out `World`s --- immutable 118current state, incorporates changes and handles out `Analysis` --- an
131consistent snapshots of `WorldState`, which actually power analysis. 119immutable consistent snapshot of world state at a point in time, which
120actually powers analysis.
132 121
133 122
134### `crates/server` 123### `crates/ra_lsp_server`
135 124
136An LSP implementation which uses `libanalysis` for managing state and 125An LSP implementation which uses `ra_analysis` for managing state and
137`libeditor` for actually doing useful stuff. 126`ra_editor` for actually doing useful stuff.
138 127
139 128
140### `crates/cli` 129### `crates/cli`
@@ -149,7 +138,7 @@ Code-gen tasks, used to develop libsyntax2:
149- `cargo gen-tests` -- collect inline tests from grammar 138- `cargo gen-tests` -- collect inline tests from grammar
150- `cargo install-code` -- build and install VS Code extension and server 139- `cargo install-code` -- build and install VS Code extension and server
151 140
152### `code` 141### `editors/code`
153 142
154VS Code plugin 143VS Code plugin
155 144
@@ -159,10 +148,10 @@ VS Code plugin
159Non-incremental, but seems pretty fast: 148Non-incremental, but seems pretty fast:
160 149
161``` 150```
162$ cargo build --release --package cli 151$ cargo build --release --package ra_cli
163$ wc -l ~/projects/rust/src/libsyntax/parse/parser.rs 152$ wc -l ~/projects/rust/src/libsyntax/parse/parser.rs
1647546 /home/matklad/projects/rust/src/libsyntax/parse/parser.rs 1537546 /home/matklad/projects/rust/src/libsyntax/parse/parser.rs
165$ ./target/release/cli parse < ~/projects/rust/src/libsyntax/parse/parser.rs --no-dump > /dev/null 154$ ./target/release/ra_cli parse < ~/projects/rust/src/libsyntax/parse/parser.rs --no-dump > /dev/null
166parsing: 21.067065ms 155parsing: 21.067065ms
167``` 156```
168 157
@@ -175,7 +164,7 @@ parsing: 21.067065ms
175 164
176## License 165## License
177 166
178libsyntax2 is primarily distributed under the terms of both the MIT license 167Rust analyzer is primarily distributed under the terms of both the MIT
179and the Apache License (Version 2.0). 168license and the Apache License (Version 2.0).
180 169
181See LICENSE-APACHE and LICENSE-MIT for details. 170See LICENSE-APACHE and LICENSE-MIT for details.
diff --git a/editors/README.md b/editors/README.md
new file mode 100644
index 000000000..798c08581
--- /dev/null
+++ b/editors/README.md
@@ -0,0 +1,89 @@
1To install experimental VS Code plugin:
2
3```
4$ cargo install-code
5```
6
7This will run `cargo install --packge ra_lsp_server` to install the
8server binary into `~/.cargo/bin`, and then will build and install
9plugin from `editors/code`. See
10[this](https://github.com/matklad/rust-analyzer/blob/cc76b0d31d8ba013c499dd3a4ca69b37004795e6/crates/tools/src/main.rs#L192)
11for details
12
13It's better to remove existing Rust plugins to avoid interference.
14
15### Features:
16
17* syntax highlighting (LSP does not have API for it, so impl is hacky
18 and sometimes fall-backs to the horrible built-in highlighting)
19
20* **Go to symbol in workspace** (`ctrl+t`)
21 - `#Foo` searches for `Foo` type in the current workspace
22 - `#foo#` searches for `foo` function in the current workspace
23 - `#Foo*` searches for `Foo` type among dependencies, excluding `stdlib`
24 - Sorry for a weired UI, neither LSP, not VSCode have any sane API for filtering! :)
25
26* **Go to symbol in file** (`alt+shift+o`)
27
28* **Go to definition** ("correct" for `mod foo;` decls, approximate for other things).
29
30* commands (`ctrl+shift+p` or keybindings)
31 - **Show Rust Syntax Tree** (use it to verify that plugin works)
32 - **Rust Extend Selection**. Extends the current selection to the
33 encompassing syntactic construct (expression, statement, item,
34 module, etc). It works with multiple cursors. Do bind this command
35 to a key, its super-useful!
36 - **Rust Matching Brace**. If the cursor is on any brace
37 (`<>(){}[]`) which is a part of a brace-pair, moves cursor to the
38 matching brace.
39 - **Rust Parent Module**. Navigate to the parent module of the current module
40 - **Rust Join Lines**. Join selected lines into one, smartly fixing
41 up whitespace and trailing commas.
42 - **Run test at caret**. When cursor is inside a function marked
43 `#[test]`, this action runs this specific test. If the cursor is
44 outside of the test function, this re-runs the last test. Do bind
45 this to a shortcut!
46
47* code actions (use `ctrl+.` to activate).
48
49`<|>` signifies cursor position
50
51- Flip `,`
52
53```
54// before:
55fn foo(x: usize,<|> dim: (usize, usize))
56// after:
57fn foo(dim: (usize, usize), x: usize)
58```
59
60- Add `#[derive]`
61
62```
63// before:
64struct Foo {
65 <|>x: i32
66}
67// after:
68#[derive(<|>)]
69struct Foo {
70 x: i32
71}
72```
73
74- Add `impl`
75
76```
77// before:
78struct Foo<'a, T: Debug> {
79 <|>t: T
80}
81// after:
82struct Foo<'a, T: Debug> {
83 t: T
84}
85
86impl<'a, T: Debug> Foo<'a, T> {
87 <|>
88}
89```