24 days of Rust - racer

Important note: this article is outdated! Go to http://zsiciarz.github.io/24daysofrust/ for a recent version of all of 24 days of Rust articles. The blogpost here is kept as it is for historical reasons.

Welcome to the second week of 24 days of Rust! Hope you enjoy the articles so far. Today let me introduce you to racer - a code completion engine for Rust.

As there is no proper Rust IDE (yet), most of us Rustaceans use some code editor such as Vim, Emacs, Atom etc. However the out-of-the-box support for Rust is very limited - if you're lucky, your editor has syntax highlighting, but not much more. We'd love to have some sort of autocompletion to ease typing, and a "go to definition" command to quickly jump around the codebase.

racer is a tool (still in development) to do just that. Follow the instructions in readme to compile it. You'll need to have the source code for Rust compiler and standard libraries on your machine. Fortunately it's just a git clone away:

$ git clone https://github.com/rust-lang/rust.git $HOME/rust
$ export RUST_SRC_PATH=$HOME/rust/src

The second line sets an environment variable that racer uses to find Rust sources. You can put that line in your .bashrc, .zshrc or whatever startup file your shell uses.

The racer executable has a few subcommands (you can see the full list by running racer with no arguments). Let's take a look at the most important ones.

Completion engine

The racer complete subcommand takes a part of some (fully qualified) Rust name and tries to find completions. For example:

$ ./bin/racer complete std::option::
MATCH Option,166,9,/home/zbyszek/Development/Rust/rust/src/libcore/option.rs,Enum,pub enum Option<T> {
MATCH Item,774,11,/home/zbyszek/Development/Rust/rust/src/libcore/option.rs,Struct,pub struct Item<A> {
MATCH None,168,4,/home/zbyszek/Development/Rust/rust/src/libcore/option.rs,EnumVariant,None,
MATCH Some,170,4,/home/zbyszek/Development/Rust/rust/src/libcore/option.rs,EnumVariant,Some(T)

The output is intended to be computer-readable, in fact you could possibly parse it as a comma-separated format (see my article on CSV in Rust).

racer completion in Vim

Find definition

The second important subcommand is racer find-definition. It expects three extra arguments: line number, column number and a filename. The first two numbers are cursor coordinates, so from the code editor's point of view racer will try to find the definition of the word under cursor. For example when run on racer's own source (the coordinates point to a File import):

$ ./bin/racer find-definition 16 15 src/main.rs
MATCH File,83,11,/home/zbyszek/Development/Rust/rust/src/libstd/io/fs.rs,Struct,pub struct File {

The output format is the same as in the case of racer complete. See how that works in Vim when I press gd with the cursor on the Option word:

find definition in Vim

Editor integrations

Vim and Emacs plugins are bundled with racer's source. For other editors there are some third-party plugins:

Code examples in this article were built with rustc 0.13.0-nightly.

Photo by nolnet and shared under the Creative Commons Attribution-NonCommercial 2.0 Generic License. See https://www.flickr.com/photos/nolnet/5310675948/