X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=README.md;h=5dcb8e12491aa64741090fccae4cca532da256c9;hb=4103068ad22216d2479dcb0534a1104dac933965;hp=6fcd7eb078d024f5501bb3501ee98e974d564ee1;hpb=2812015d40c94ddb94bb57ed1a9811ff24414c44;p=rust.git diff --git a/README.md b/README.md index 6fcd7eb078d..5dcb8e12491 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,87 @@ -# libsyntax2.0 +# Rust Analyzer -[![Join the chat at https://gitter.im/libsyntax2/Lobby](https://badges.gitter.im/libsyntax2/Lobby.svg)](https://gitter.im/libsyntax2/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) -[![Build Status](https://travis-ci.org/matklad/libsyntax2.svg?branch=master)](https://travis-ci.org/matklad/libsyntax2) -[![Build status](https://ci.appveyor.com/api/projects/status/j56x1hbje8rdg6xk/branch/master?svg=true)](https://ci.appveyor.com/project/matklad/libsyntax2/branch/master) +[![Build Status](https://travis-ci.org/matklad/rust-analyzer.svg?branch=master)](https://travis-ci.org/matklad/rust-analyzer) +[![Build status](https://ci.appveyor.com/api/projects/status/j56x1hbje8rdg6xk/branch/master?svg=true)](https://ci.appveyor.com/project/matklad/rust-analyzer/branch/master) -libsyntax2.0 is an **experimental** parser of the Rust language, -intended for the use in IDEs. -[RFC](https://github.com/rust-lang/rfcs/pull/2256). +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. ## Quick Start +Rust analyzer builds on stable Rust >= 1.29.0. + ``` +# run tests $ cargo test -$ cargo parse < crates/libsyntax2/src/lib.rs -``` - - -## Trying It Out -This installs experimental VS Code plugin +# show syntax tree of a Rust file +$ 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 ``` -$ cargo install-code -``` - -It's better to remove existing Rust plugins to avoid interference. -Warning: plugin is not intended for general use, has a lot of rough -edges and missing features (notably, no code completion). That said, -while originally libsyntax2 was developed in IntelliJ, @matklad now -uses this plugin (and thus, libsytax2) to develop libsyntax2, and it -doesn't hurt too much :-) - -### Features: - -* syntax highlighting (LSP does not have API for it, so impl is hacky - and sometimes fall-backs to the horrible built-in highlighting) - -* commands (`ctrl+shift+p` or keybindings) - - **Show Rust Syntax Tree** (use it to verify that plugin works) - - **Rust Extend Selection** (works with multiple cursors) - - **Rust Matching Brace** (knows the difference between `<` and `<`) - - **Rust Parent Module** - - **Rust Join Lines** (deals with trailing commas) +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. + + +## 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 +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. + +Rust Analyzer is a hobby 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: + +* 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. -* **Go to symbol in file** - -* **Go to symbol in workspace** (no support for Cargo deps yet) - -* code actions: - - Flip `,` in comma separated lists - - Add `#[derive]` to struct/enum - - Add `impl` block to struct/enum - - Run tests at caret +* 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. -* **Go to definition** ("correct" for `mod foo;` decls, index-based for functions). - +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. ## Code Walk-Through -### `crates/libsyntax2` +### `crates/ra_syntax` + +Rust syntax tree structure and parser. See +[RFC](https://github.com/rust-lang/rfcs/pull/2256) for some design +notes. - `yellow`, red/green syntax tree, heavily inspired [by this](https://github.com/apple/swift/tree/ab68f0d4cbf99cdfa672f8ffe18e433fddc8b371/lib/Syntax) - `grammar`, the actual parser @@ -71,27 +91,38 @@ doesn't hurt too much :-) - `algo`: generic tree algorithms, including `walk` for O(1) stack space tree traversal (this is cool) and `visit` for type-driven visiting the nodes (this is double plus cool, if you understand how - `Visitor` works, you understand libsyntax2). - + `Visitor` works, you understand rust-analyzer). + + +### `crates/ra_editor` + +All IDE features which can be implemented if you only have access to a +single file. `ra_editor` could be used to enhance editing of Rust code +without the need to fiddle with build-systems, file +synchronization and such. -### `crates/libeditor` +In a sense, `ra_editor` is just a bunch of pure functions which take a +syntax tree as an input. -Most of IDE features leave here, unlike `libanalysis`, `libeditor` is -single-file and is basically a bunch of pure functions. +### `crates/salsa` +An implementation of red-green incremental compilation algorithm from +rust compiler. It makes all rust-analyzer features on-demand. -### `crates/libanalysis` + +### `crates/ra_analysis` A stateful library for analyzing many Rust files as they change. -`WorldState` is a mutable entity (clojure's atom) which holds current -state, incorporates changes and handles out `World`s --- immutable -consistent snapshots of `WorldState`, which actually power analysis. +`AnalysisHost` is a mutable entity (clojure's atom) which holds +current state, incorporates changes and handles out `Analysis` --- an +immutable consistent snapshot of world state at a point in time, which +actually powers analysis. -### `crates/server` +### `crates/ra_lsp_server` -An LSP implementation which uses `libanalysis` for managing state and -`libeditor` for actually doing useful stuff. +An LSP implementation which uses `ra_analysis` for managing state and +`ra_editor` for actually doing useful stuff. ### `crates/cli` @@ -100,20 +131,39 @@ A CLI interface to libsyntax ### `crate/tools` -Code-gen tasks, used to develop libsyntax2: +Code-gen tasks, used to develop rust-analyzer: - `cargo gen-kinds` -- generate `ast` and `syntax_kinds` - `cargo gen-tests` -- collect inline tests from grammar - `cargo install-code` -- build and install VS Code extension and server -### `code` +### `editors/code` VS Code plugin +## Performance + +Non-incremental, but seems pretty fast: + +``` +$ cargo build --release --package ra_cli +$ wc -l ~/projects/rust/src/libsyntax/parse/parser.rs +7546 /home/matklad/projects/rust/src/libsyntax/parse/parser.rs +$ ./target/release/ra_cli parse < ~/projects/rust/src/libsyntax/parse/parser.rs --no-dump > /dev/null +parsing: 21.067065ms +``` + +## Getting in touch + +@matklad can be found at Rust +[discord](https://discordapp.com/invite/rust-lang), in +#ides-and-editors. + + ## License -libsyntax2 is primarily distributed under the terms of both the MIT license -and the Apache License (Version 2.0). +Rust analyzer is primarily distributed under the terms of both the MIT +license and the Apache License (Version 2.0). See LICENSE-APACHE and LICENSE-MIT for details.