# Debugging and Troubleshooting

Some tips and advice for debugging issues with the RLS. Many of these issues are
specific to the Visual Studio Code extension.

Where we mention settings, below, we usually mean Visual Studio Code's settings.
These can be set per-user and per-project, and can be found in the `File >
Preferences > Settings` menu.


## Common problems

### Missing Rustup

The only external component that the VSCode extension requires is Rustup. It
will install everything else (RLS, even Rust) itself.

You can install Rustup from [rustup.rs](https://www.rustup.rs/). The extension
should warn you if it is not present. See the extension section below for more
issues.


### Missing RLS component

You might see an error like `toolchain 'nightly-x86_64-unknown-linux-gnu' does not contain component 'rls-preview' for target 'x86_64-unknown-linux-gnu'`.

This is due to a nightly release missing the RLS component. That
happens occasionally when the RLS cannot be built with the current compiler. To
work around this issue you can use an RLS from the beta or stable channels, wait
for a new nightly which does contain the RLS component, or use an older nightly
which includes the RLS component. To do the latter follow [these
instructions](https://github.com/rust-lang-nursery/rls-vscode/issues/181#issue-269383659),
then avoid `rustup update`.

### Out of date components

Run `rustup update` from the command line to make sure Rust, the RLS, and
associated data are all up to date.


### Project has both a library and a binary

The RLS can currently only work with one target at a time. By default, the RLS
works with the binary, if there is only one. You can build the library by
setting `rust.build_lib` to `true` (this is often most useful). If you have
multiple binaries, you can specify one to work with using `rust.build_bin`.

Auto-detection for some of this should be in the next release.


### Cargo workspaces

Currently there is only experimental, work-in-progress support for Cargo
workspaces. We recommend you don't use the RLS with such projects for now, and
stay tuned for updates.


### Opening a Rust file outside of a project

Before opening a Rust file, the RLS needs to be aware of the whole crate. That
means you need to have opened the folder containing `Cargo.toml` in VSCode
before opening a Rust file (which triggers loading the Rust extension).


### Information for paths

If you have a path such as `foo::bar::baz`, the RLS only has information for the
last segment of the path. That means you can only 'goto def' or get type
information on hover for `baz`, not for `foo` or `bar`. This is a limitation in
the Rust compiler, but should be addressed at some point.


### Tests, examples

The RLS currently only works with the main part of a crate. It does not work
with the tests or examples folders.

The RLS can give information about unit tests, you need to set `rust.cfg_test`
to `true` (note that this will cause a lot of 'unused code' warnings, which is
why it is off by default).


### Stale data

Stale data can often trip up or slow down the RLS. It can be  worth running `cargo
clean` and/or deleting the entire `target` directory for your crate. You'll need
to restart the extension after doing this to get a proper rebuild.

It is also possible (but rarer) that Rustup gets into a bad place with stale
data. You can reinstall rustup and/or delete its cache (in `~/.rustup`) to try
and solve this.


### Deprecated environment variables

If you were using early versions of the RLS and extension, you might have used
`RLS_PATH` or `RLS_ROOT` env vars. These can cause issues now, so remove them
from your environment (this won't be necessary with the next release of the
extension).


## Extension issues

We recommend using our [VSCode extension](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust).
Note that there are other VSCode extensions.

Ensure the extension and VSCode is up to date. You can check the latest version
of VSCode on [their website](https://code.visualstudio.com/). You can see your
version in the `Help > About` menu item. VSCode should tell you if it or your
extension are not up to date.

The extension must be able to run Rustup. If Rustup is installed, it must be in
your PATH. Note that if you run VSCode from an icon or launcher, the PATH may
not be the same as from a terminal. You can check this issue by running VSCode
from your terminal (`code` should work).


## Project issues

It can be useful to determine if a problem is with your environment or with a
project. Try running the VSCode extension with a very simple project. Use `cargo
new foo --bin` to create a new project called `foo`, open the `foo` folder in
VSCode. Add a local variable and a use of it, see if the RLS gives you the type
of the variable on hover and if you can jump to its definition.

If the above works, then you probably have project issues. If it
doesn't, then there is a problem with the environment.

If a project has a lot of dependencies, initial indexing might take a long time.
In general, initial indexing should take about the same time as a full compile of
the project (usually a little less time, but that depends).

If the primary crate of a project is large, it probably won't work well with the
RLS (too slow). Exactly what 'large' means here will depend on how fast your
machine is and how tolerant of latency you are.

Projects with Cargo workspaces will not work (for now).

Projects with non-Cargo build systems will not work (you *might* be able to make
this work with some effort, talk to nrc on irc).

Rarely, there are problems with the RLS's build model. You can try running
`cargo check` on the command line to emulate the build model outside of the IDE.


### Crates with large data files

Some crates can have surprisingly large data files. Large data files can slow
down the RLS to the point of crashing (or appearing to crash). Check the json
files in the `target/rls/deps/save-analysis` directory. Anything over 1mb is
suspicious. You can test if this is important by deleting the json file(s) and
restarting the extension (you'd have to do this every time you do a full build,
for example after `cargo clean` or updating the toolchain).

If you find such large data files, please report an issue on this repo. We can
try to optimise the data, or blacklist the crate.


## Racer vs compiler issues

The RLS uses Racer for code completion, and the compiler for everything else
(such as type on hover). If you are getting code completion options but not type
on hover, etc., then there is probably an issue with the RLS getting data from
the compiler. If you have type on hover, but poor code completion, then it is
probably a Racer issue.

Racer and the rest of the RLS use different data sources for indexing the
standard libraries. If you have Racer problems with the standard libraries, then
it is worth checking the `rust-source` component. If Racer is working, but other
things are not, it is worth checking the `rust-analysis` component (both
components are delivered by Rustup).


## Logging

When using VSCode extension, you can view error messages and logging in the
Output window, under View > Output, in the 'Rust Language Server' channel
that can be selected in the dropdown menu on the right of the panel.

To see more info in the logs, set `RUST_LOG=rls=debug` in your environment. You
can also set `RUST_LOG=rls_analysis=debug` to see logging specific to the
data analysis. In general, these will be printed to the standard error stream
of the server.

If you are seeing crashes in the logs, you can get a backtrace by setting
`RUST_BACKTRACE=1`.

You can also dump to a file by setting `rust-client.logToFile` to `true` in the
VSCode extension. The file will be in the project root; each time you start the
extension, you'll get a new file.

You can get more info about VSCode and the extension itself by running VSCode
with `--verbose`. However, I have only rarely found this to be useful. You can
also use VSCode's debugger to debug the extension. This can be useful if the
extension hangs.

It might be useful to find the `rls` process and attach a debugger to it.
However, with an optimised build and no debug symbols, this is not likely to be
useful.


## Library issues

If you get an error like `error while loading shared libraries` while starting
up the RLS, you should try the following:

On Linux:

```
export LD_LIBRARY_PATH=$(rustc --print sysroot)/lib:$LD_LIBRARY_PATH
```

On MacOS (this might only work if SIP is disabled (depending on how you run the
RLS), you could modify the environment in the client):

```
export DYLD_LIBRARY_PATH=$(rustc --print sysroot)/lib:$DYLD_LIBRARY_PATH
```

(This should not happen if you are using Rustup, only if building and running
from source).


## Getting more help

Please feel free to [open an issue](https://github.com/rust-lang-nursery/rls/issues/new)
to discuss any problem.

If you use irc, you can ask in #rust-dev-tools on the Mozilla network. You can
ping nrc.