Repository files navigation

RLS has been deprecated and is no longer supported.It has been replaced withrust-analyzer.Users are encouraged to uninstall RLS and follow the instructions in therust-analyzer manual to install it for your editor.

The RLS provides a server that runs in the background, providing IDEs,editors, and other tools with information about Rust programs. It supportsfunctionality such as 'goto definition', symbol search, reformatting, and codecompletion, and enables renaming and refactorings.

A high-level overview of the architecture can be foundhere.

The RLS gets its source data from the compiler and fromRacer. Where possible it uses data fromthe compiler which is precise and complete. Where it is not possible, (for examplefor code completion and where building is too slow), it uses Racer.

Since the Rust compiler does not yet support end-to-end incremental compilation,we can't offer a perfect experience. However, by optimising our use of thecompiler and falling back to Racer, we can offer a pretty good experience forsmall to medium sized crates. As the RLS and compiler evolve, we'll offer abetter experience for larger and larger crates.

The RLS is designed to be frontend-independent. We hope it will be widelyadopted by different editors and IDEs. To seed development, we provide areference implementation of an RLS frontendforVisual Studio Code.

You can installrustup on many platforms. This will help us quickly install theRLS and its dependencies.

If you already have rustup installed, update to ensure you have the latestrustup and compiler:

rustup update

If you're going to use the VSCode extension, you can skip step 2.

Once you have rustup installed, run the following commands:

rustup component add rls rust-analysis rust-src

The development of rustc's internals is quite fast paced. Downstream projects that rely on nightly internals, particularly clippy, can break fairly often because of this.

When such breakages occur the nightly release will be missing rls. This is a trade-off compared with the other option of just not publishing the night's release, but does avoid blocking the rust nightly releases for people that don't need clippy/rls.

To mitigate the issues we have:

• rustup will warn if the update is missing any components you currently have. This means you can no longer accidentally update to a no-rls release. Once rls is available again it'll update.
• rls, clippy are available on the stable channel. Meaning most developers installing for the first time should use stable.
• However, if you need latest nightly rls you can usehttps://rust-lang.github.io/rustup-components-history/ to find and install a dated nightly release ierustup install nightly-2018-12-06.

Also see#641.

The RLS is built to work with many IDEs and editors, we mostly useVSCode to test the RLS. The easiest way is to use thepublished extension.

You'll know it's working when you see this in the status bar at the bottom, witha spinning indicator:

RLS: working ◐

Once you see:

RLS

Then you have the full set of capabilities available to you. You can goto def,find all refs, rename, goto type, etc. Completions are also available using theheuristics that Racer provides. As you type, your code will be checked anderror squiggles will be reported when errors occur. You can hover thesesquiggles to see the text of the error.

The RLS can be configured on a per-project basis; using the VisualStudio Code extension this will be done via the workspace settings filesettings.json.

Other editors will have their own way of sending theworkspace/DidChangeConfigurationmethod. Options are nested in therust object, so your LSP client might send{"settings":{"rust":{"unstable_features":true}}} as parameters.

Entries in this file will affect how the RLS operates and how it builds yourproject.

Currently we accept the following options:

• unstable_features (bool, defaults tofalse) enables unstable features.Currently no option requires this flag.
• sysroot (String, defaults to"") if the given string is not empty, usethe given path as the sysroot for all rustc invocations instead of trying todetect the sysroot automatically
• target (String, defaults to"") if the given string is not empty, usethe given target triple for all rustc invocations
• wait_to_build (u64) overrides build debounce duration (ms). This is otherwise automaticallyinferred by the latest build duration.
• all_targets (bool, defaults totrue) checks the project as if you wererunningcargo check --all-targets. I.e., check all targets and integrationtests too
• crate_blacklist ([String], defaults tothis list)allows to specify which crates should be skipped by the RLS.By default skips libraries that are of considerable size but which the useroften may not be directly interested in, thus reducing the build latency.
• build_on_save (bool, defaults tofalse) toggles whether the RLS shouldperform continuous analysis or only after a file is saved
• features ([String], defaults to empty) list of Cargo features to enable
• all_features (bool, defaults tofalse) enables all Cargo features
• no_default_features (bool, defaults tofalse) disables default Cargofeatures
• racer_completion (bool, defaults totrue) enables code completion usingracer (which is, at the moment, our only code completion backend). Also enableshover tooltips & go-to-definition to fall back to racer when save-analysis data is unavailable.
• clippy_preference (String, defaults to"opt-in") controls eagerness of clippydiagnostics when available. Valid values are(case-insensitive):
  • "off" Disable clippy lints.
  • "on" Display the same diagnostics as command-line clippy invoked with no arguments (clippy::all unless overridden).
  • "opt-in" Only display the lintsexplicitly enabled in the code. Start by adding#![warn(clippy::all)] to the root of each crate you want linted.

and the following unstable options:

• build_lib (bool, defaults tofalse) checks the project as if you passedthe--lib argument to cargo. Mutually exclusive with, and preferred over,build_bin.
• build_bin (String, defaults to"") checks the project as if you passed-- bin <build_bin> argument to cargo. Mutually exclusive withbuild_lib.
• cfg_test (bool, defaults tofalse) checks the project as if you wererunningcargo test rather thancargo build. I.e., compiles (but does notrun) test code.
• full_docs (bool, defaults tofalse) instructs rustc to populate thesave-analysis data with full source documentation. When set tofalse, only thefirst paragraph is recorded. This optioncurrently has little to no effect onhover tooltips. The save-analysis docs are only used if source extraction fails.This option has no effect on the standard library.
• show_hover_context (bool, defaults totrue) show additional context inhover tooltips when available. This is often the local variable declaration.When set to false the content is only available when holding thectrl key insome editors.

For tips on debugging and troubleshooting, seedebugging.md.

You can look in thecontributing.mdin this repo to learn more about contributing to this project.

If you want to implement RLS support in an editor, seeclients.md.