README.md

   1 # Rust Analyzer
   2
   3 [![Build Status](https://travis-ci.org/matklad/rust-analyzer.svg?branch=master)](https://travis-ci.org/matklad/rust-analyzer)
   4 [![Build status](https://ci.appveyor.com/api/projects/status/j56x1hbje8rdg6xk/branch/master?svg=true)](https://ci.appveyor.com/project/matklad/rust-analyzer/branch/master)
   5
   6
   7 Rust Analyzer is an **experimental** modular compiler frontend for the
   8 Rust language, which aims to lay a foundation for excellent IDE
   9 support.
  10
  11 It doesn't implement much of compiler functionality yet, but the
  12 white-space preserving Rust parser works, and there are significant
  13 chunks of overall architecture (indexing, on-demand & lazy
  14 computation, snapshotable world view) in place. Some basic IDE
  15 functionality is provided via a language server.
  16
  17 ## Quick Start
  18
  19 ```
  20 $ cargo test
  21 $ cargo parse < crates/libsyntax2/src/lib.rs
  22 ```
  23
  24 ## Trying It Out
  25
  26 This installs experimental VS Code plugin
  27
  28 ```
  29 $ cargo install-code
  30 ```
  31
  32 It's better to remove existing Rust plugins to avoid interference.
  33 Warning: plugin is not intended for general use, has a lot of rough
  34 edges and missing features (notably, no code completion). That said,
  35 while originally libsyntax2 was developed in IntelliJ, @matklad now
  36 uses this plugin (and thus, libsytax2) to develop libsyntax2, and it
  37 doesn't hurt too much :-)
  38
  39
  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
  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
  68 ## Current Status and Plans
  69
  70 Rust analyzer aims to fill the same niche as the official [Rust
  71 Language Server](https://github.com/rust-lang-nursery/rls), but
  72 better. It was created because @matklad is not satisfied with RLS
  73 original starting point and current direction. More details can be
  74 found [in this
  75 thread](https://internals.rust-lang.org/t/2019-strategy-for-rustc-and-the-rls/8361).
  76 The core issue is that RLS works in the "wait until user stops typing,
  77 run the build process, save the results of the analysis" mode, which
  78 arguably is the wrong foundation for IDE (see the thread for details).
  79
  80 Rust Analyzer is a hobby project at the moment, there's exactly zero
  81 guarantees that it becomes production-ready one day.
  82
  83 The near/mid term plan is to work independently of the main rustc
  84 compiler and implement at least simplistic versions of name
  85 resolution, macro expansion and type inference. The purpose is two
  86 fold:
  87
  88 * to quickly bootstrap usable and useful language server: solution
  89   that covers 80% of Rust code will be useful for IDEs, and will be
  90   vastly simpler than 100% solution.
  91
  92 * to understand how the consumer-side of compiler API should look like
  93   (especially it's on-demand aspects). If you have
  94   `get_expression_type` function, you can write a ton of purely-IDE
  95   features on top of it, even if the function is only partially
  96   correct. Plugin in the precise function afterwards should just make
  97   IDE features more reliable.
  98
  99 The long term plan is to merge with the mainline rustc compiler,
 100 probably around the HIR boundary? That is, use rust analyzer for
 101 parsing, macro expansion and related bits of name resolution, but
 102 leave the rest (including type inference and trait selection) to the
 103 existing rustc.
 104
 105 ## Code Walk-Through
 106
 107 ### `crates/libsyntax2`
 108
 109 - `yellow`, red/green syntax tree, heavily inspired [by this](https://github.com/apple/swift/tree/ab68f0d4cbf99cdfa672f8ffe18e433fddc8b371/lib/Syntax)
 110 - `grammar`, the actual parser
 111 - `parser_api/parser_impl` bridges the tree-agnostic parser from `grammar` with `yellow` trees
 112 - `grammar.ron` RON description of the grammar, which is used to
 113   generate `syntax_kinds` and `ast` modules.
 114 - `algo`: generic tree algorithms, including `walk` for O(1) stack
 115   space tree traversal (this is cool) and `visit` for type-driven
 116   visiting the nodes (this is double plus cool, if you understand how
 117   `Visitor` works, you understand libsyntax2).
 118
 119
 120 ### `crates/libeditor`
 121
 122 Most of IDE features leave here, unlike `libanalysis`, `libeditor` is
 123 single-file and is basically a bunch of pure functions.
 124
 125
 126 ### `crates/libanalysis`
 127
 128 A stateful library for analyzing many Rust files as they change.
 129 `WorldState` is a mutable entity (clojure's atom) which holds current
 130 state, incorporates changes and handles out `World`s --- immutable
 131 consistent snapshots of `WorldState`, which actually power analysis.
 132
 133
 134 ### `crates/server`
 135
 136 An LSP implementation which uses `libanalysis` for managing state and
 137 `libeditor` for actually doing useful stuff.
 138
 139
 140 ### `crates/cli`
 141
 142 A CLI interface to libsyntax
 143
 144 ### `crate/tools`
 145
 146 Code-gen tasks, used to develop libsyntax2:
 147
 148 - `cargo gen-kinds` -- generate `ast` and `syntax_kinds`
 149 - `cargo gen-tests` -- collect inline tests from grammar
 150 - `cargo install-code` -- build and install VS Code extension and server
 151
 152 ### `code`
 153
 154 VS Code plugin
 155
 156
 157 ## Performance
 158
 159 Non-incremental, but seems pretty fast:
 160
 161 ```
 162 $ cargo build --release --package cli
 163 $ wc -l ~/projects/rust/src/libsyntax/parse/parser.rs
 164 7546 /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
 166 parsing: 21.067065ms
 167 ```
 168
 169 ## Getting in touch
 170
 171 @matklad can be found at Rust
 172 [discord](https://discordapp.com/invite/rust-lang), in
 173 #ides-and-editors.
 174
 175
 176 ## License
 177
 178 libsyntax2 is primarily distributed under the terms of both the MIT license
 179 and the Apache License (Version 2.0).
 180
 181 See LICENSE-APACHE and LICENSE-MIT for details.