Learn Rust by debugging Rust

In my previous article about rustup, I showed you how to install the Rust toolchain. Well, what good is the toolchain if you won’t be using it to get more hands-on with Rust? Learning any language involves reading existing code and writing a lot of sample programs. That's a good way to become proficient in a language. However, there's a third way: debugging code.

Learning through debugging involves trying to compile a pre-written (buggy) sample program, understanding the errors generated by the compiler, fixing the sample code, and then re-compiling it. Repeat that process until the code successfully compiles and runs.

Rustlings is an open source project by the Rust team that helps you learn Rust through the process of debugging. It also provides you with a lot of hints along the way. If you're a beginner to Rust and have either started or completed reading the Rust book, then rustlings is the ideal next step. Rustlings helps you apply what you've learned from the book, and move to working on bigger projects.

Installing rustlings

I'm using (and recommend) a Fedora machine to try rustlings, but any Linux distribution works. To install rustlings, you must download and run its install script. It's recommended that you do this as a normal user (not root) without any special privileges.

Remember, for you to be able to use rustlings, you need the Rust toolchain available on your system. If you don't have that already, please refer to my article on rustup.

Once you're ready, download the installation script:

$ curl -L https://raw.githubusercontent.com/rust-lang/rustlings/main/install.sh  > rustlings_install.sh
$ file rustlings_install.sh
rustlings_install.sh: Bourne-Again shell script, ASCII text executable

Inspect the script to learn what it does:

$ less rustlings_install.sh

And then run it to install:

$ bash rustlings_install.sh
[...]
Installing /home/tux/.cargo/bin/rustlings
Installed package `rustlings v4.8.0 (/home/tux/rustlings)` (executable `rustlings`)
All done!

Run 'rustlings' to get started.

Rustlings exercises

The installation provides you with the rustlings command. Run it along with the --help flag to see what options are available.

$ rustlings --help

The installation script also clones the rustlings Git repository, and installs all the dependencies required to run the sample programs. You can view the sample programs within the exercises directory under rustlings:

$ cd rustlings
$ pwd
/home/tux/rustlings
$ ls
AUTHORS.md  Cargo.toml        CONTRIBUTING.md  info.toml install.sh README.md  target Cargo.lock  CHANGELOG.md  exercises install.ps1  LICENSE src tests
$ ls -m exercises/
advanced_errors, clippy, collections, conversions, enums, error_handling, functions, generics, if, intro, macros, mod.rs, 
modules, move_semantics, option, primitive_types, quiz1.rs, quiz2.rs, quiz3.rs, quiz4.rs, README.md, 
standard_library_types, strings, structs, tests, threads, traits, variables

List all exercises from the command line

The rustlings command provides you with a list command which displays each sample program, its complete path, and the status (which defaults to pending.)

$ rustlings list
Name         Path                                 Status
intro1       exercises/intro/intro1.rs            Pending
intro2       exercises/intro/intro2.rs            Pending
variables1   exercises/variables/variables1.rs    Pending
variables2   exercises/variables/variables2.rs    Pending
variables3   exercises/variables/variables3.rs    Pending
[...]

Near the end of the output, you're given a progress report so you can track your work.

Progress: You completed 0 / 84 exercises (0.00 %).

View sample programs

The rustings list command shows you what programs are available, so at any time you can view the code of those programs by copying the complete paths into your terminal as an argument for the cat or less commands:

$ cat exercises/intro/intro1.rs

Verify your programs

Now you can start debugging programs. You can do that using the verify command. Notice that rustlings chooses the first program in the list (intro1.rs), tries to compile it, and succeeds:

$ rustlings verify
Progress: [-----------------------------------] 0/84
✅ Successfully ran exercises/intro/intro1.rs!

You can keep working on this exercise,
or jump into the next one by removing the `I AM NOT DONE` comment:

 6 |  // Execute the command `rustlings hint intro1` for a hint.
 7 |  
 8 |  // I AM NOT DONE
 9 |

As you can see from the output, even though the sample code compiles, there's work yet to be done. Each sample program has the following comment in its source file:

$ grep "NOT DONE" exercises/intro/intro1.rs
// I AM NOT DONE

Although the compilation of the first program worked fine, rustlings won't move to the next program until you remove the I AM NOT DONE comment.

Moving to the next exercise

Once you have removed the comment from intro1.rs, you can move to the next exercise by running the rustlings verify command again. This time, you may notice that rustlings tries to compile the next program (intro2.rs) in the series, but runs into an error. You're expected to debug that issue, fix it, and then move forward. This is a critical step, allowing you to understand why Rust says a program has bugs.

$ rustlings verify
Progress: [>------------------------] 1/84
⚠️  Compiling of exercises/intro/intro2.rs failed! Please try again. Here's the output:
error: 1 positional argument in format string, but no arguments were given
 --> exercises/intro/intro2.rs:8:21
  |
8 |         println!("Hello {}!");
  |                         ^^

error: aborting due to previous error

Getting a hint

Rustlings has a handy hint argument, which tells you exactly what's wrong with the sample program, and how to fix it. You can think of it as an add-on help option, in addition to what the compiler error message tells you.

$ rustlings hint intro2
Add an argument after the format string.

Based on the above hint, fixing the program is easy. All you need to do is add an additional argument to the println statement. This diff should help you understand the changes:

< println!("Hello {}!", "world");
---
> println!("Hello {}!");

Once you make that change, and removed the NOT DONE comment from the source code, you can run rustlings verify again to compile and run the code.

$ rustlings verify
Progress: [>-------------------------------------] 1/84
✅ Successfully ran exercises/intro/intro2.rs!

Track progress

You aren't going to finish all of the exercises in a day, and it's easy to lose track of where you left off. You can run the list command to see the status of your work.

$ rustlings list
Name         Path                                  Status
intro1       exercises/intro/intro1.rs             Done   
intro2       exercises/intro/intro2.rs             Done   
variables1   exercises/variables/variables1.rs     Pending
variables2   exercises/variables/variables2.rs     Pending
variables3   exercises/variables/variables3.rs     Pending
[...]

Run specific exercises

If you don't want to start from the beginning and skip a few exercises, rustlings allows you to focus on specific exercises using the rustlings run command. This runs a specific program without requiring the previous lesson to be verified. For example:

$ rustlings run intro2
Hello world!
✅ Successfully ran exercises/intro/intro2.rs
$ rustlings run variables1

Typing exercise names can become tedious, but rustlings provides you with a handy next command so you can move to the next exercise in the series.

$ rustlings run next

Alternative watch command

If you don't want to keep typing verify after each modification you make, you can run the watch command in a terminal window, and then keep modifying the source code to fix issues. The watch command detects these modifications, and keeps re-compiling the program to see whether the issue has been fixed.

$ rustlings watch

Learn by debugging

The Rust compiler is known to provide very meaningful error messages, which helps you understand issues in your code. This usually leads to faster debugging. Rustlings is a great way to practice Rust, to get used to reading error messages, and understand the Rust language. Check out the recent features of Rustlings 5.0.0 on GitHub.

[ Practice programming with Rust. Download our Rust cheat sheet. ]