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 Rust analyzer builds on stable Rust >= 1.29.0.
  20
  21 ```
  22 # run tests
  23 $ cargo test
  24
  25 # show syntax tree of a Rust file
  26 $ cargo run --package ra_cli parse < crates/ra_syntax/src/lib.rs
  27
  28 # show symbols of a Rust file
  29 $ cargo run --package ra_cli symbols < crates/ra_syntax/src/lib.rs
  30 ```
  31
  32 To try out the language server, see [these
  33 instructions](./editors/README.md). Please note that the server is not
  34 ready for general use yet. If you are looking for a Rust IDE that
  35 works, use [IntelliJ
  36 Rust](https://github.com/intellij-rust/intellij-rust) or
  37 [RLS](https://github.com/rust-lang-nursery/rls). That being said, the
  38 basic stuff works, and rust analyzer is developed in the rust analyzer
  39 powered editor.
  40
  41
  42 ## Current Status and Plans
  43
  44 Rust analyzer aims to fill the same niche as the official [Rust
  45 Language Server](https://github.com/rust-lang-nursery/rls), but
  46 better. It was created because @matklad is not satisfied with RLS
  47 original starting point and current direction. More details can be
  48 found [in this
  49 thread](https://internals.rust-lang.org/t/2019-strategy-for-rustc-and-the-rls/8361).
  50 The core issue is that RLS works in the "wait until user stops typing,
  51 run the build process, save the results of the analysis" mode, which
  52 arguably is the wrong foundation for IDE (see the thread for details).
  53
  54 Rust Analyzer is a hobby project at the moment, there's exactly zero
  55 guarantees that it becomes production-ready one day.
  56
  57 The near/mid term plan is to work independently of the main rustc
  58 compiler and implement at least simplistic versions of name
  59 resolution, macro expansion and type inference. The purpose is two
  60 fold:
  61
  62 * to quickly bootstrap usable and useful language server: solution
  63   that covers 80% of Rust code will be useful for IDEs, and will be
  64   vastly simpler than 100% solution.
  65
  66 * to understand how the consumer-side of compiler API should look like
  67   (especially it's on-demand aspects). If you have
  68   `get_expression_type` function, you can write a ton of purely-IDE
  69   features on top of it, even if the function is only partially
  70   correct. Plugin in the precise function afterwards should just make
  71   IDE features more reliable.
  72
  73 The long term plan is to merge with the mainline rustc compiler,
  74 probably around the HIR boundary? That is, use rust analyzer for
  75 parsing, macro expansion and related bits of name resolution, but
  76 leave the rest (including type inference and trait selection) to the
  77 existing rustc.
  78
  79 ## Code Walk-Through
  80
  81 ### `crates/ra_syntax`
  82
  83 Rust syntax tree structure and parser. See
  84 [RFC](https://github.com/rust-lang/rfcs/pull/2256) for some design
  85 notes.
  86
  87 - `yellow`, red/green syntax tree, heavily inspired [by this](https://github.com/apple/swift/tree/ab68f0d4cbf99cdfa672f8ffe18e433fddc8b371/lib/Syntax)
  88 - `grammar`, the actual parser
  89 - `parser_api/parser_impl` bridges the tree-agnostic parser from `grammar` with `yellow` trees
  90 - `grammar.ron` RON description of the grammar, which is used to
  91   generate `syntax_kinds` and `ast` modules.
  92 - `algo`: generic tree algorithms, including `walk` for O(1) stack
  93   space tree traversal (this is cool) and `visit` for type-driven
  94   visiting the nodes (this is double plus cool, if you understand how
  95   `Visitor` works, you understand rust-analyzer).
  96
  97
  98 ### `crates/ra_editor`
  99
 100 All IDE features which can be implemented if you only have access to a
 101 single file. `ra_editor` could be used to enhance editing of Rust code
 102 without the need to fiddle with build-systems, file
 103 synchronization and such.
 104
 105 In a sense, `ra_editor` is just a bunch of pure functions which take a
 106 syntax tree as an input.
 107
 108 ### `crates/salsa`
 109
 110 An implementation of red-green incremental compilation algorithm from
 111 rust compiler. It makes all rust-analyzer features on-demand.
 112
 113
 114 ### `crates/ra_analysis`
 115
 116 A stateful library for analyzing many Rust files as they change.
 117 `AnalysisHost` is a mutable entity (clojure's atom) which holds
 118 current state, incorporates changes and handles out `Analysis` --- an
 119 immutable consistent snapshot of world state at a point in time, which
 120 actually powers analysis.
 121
 122
 123 ### `crates/ra_lsp_server`
 124
 125 An LSP implementation which uses `ra_analysis` for managing state and
 126 `ra_editor` for actually doing useful stuff.
 127
 128
 129 ### `crates/cli`
 130
 131 A CLI interface to libsyntax
 132
 133 ### `crate/tools`
 134
 135 Code-gen tasks, used to develop rust-analyzer:
 136
 137 - `cargo gen-kinds` -- generate `ast` and `syntax_kinds`
 138 - `cargo gen-tests` -- collect inline tests from grammar
 139 - `cargo install-code` -- build and install VS Code extension and server
 140
 141 ### `editors/code`
 142
 143 VS Code plugin
 144
 145
 146 ## Performance
 147
 148 Non-incremental, but seems pretty fast:
 149
 150 ```
 151 $ cargo build --release --package ra_cli
 152 $ wc -l ~/projects/rust/src/libsyntax/parse/parser.rs
 153 7546 /home/matklad/projects/rust/src/libsyntax/parse/parser.rs
 154 $ ./target/release/ra_cli parse < ~/projects/rust/src/libsyntax/parse/parser.rs --no-dump  > /dev/null
 155 parsing: 21.067065ms
 156 ```
 157
 158 ## Getting in touch
 159
 160 @matklad can be found at Rust
 161 [discord](https://discordapp.com/invite/rust-lang), in
 162 #ides-and-editors.
 163
 164
 165 ## License
 166
 167 Rust analyzer is primarily distributed under the terms of both the MIT
 168 license and the Apache License (Version 2.0).
 169
 170 See LICENSE-APACHE and LICENSE-MIT for details.