Learning Rust - The Toolchain

While I was writing the follow up to the first “Learning Rust” blog post (still working on it), I thought covering the Rust toolchain in a little more detail would be helpful. So, here it is…

What is the "toolchain"?

A toolchain is the set of command line programs and libraries (sometimes called an SDK) that provide the basics for creating applications. For a compiled language like Rust this includes:

• The compiler, and possibly other tools to convert compiler output into executable code.
• A package manager.
• Maybe an analysis tool of some sort (linter)
• Standard libraries
• Documentation

The Rust Toolchain

So what does this look like for Rust?

Mostly you will be dealing with two command line tools:

1. rustup
2. cargo

Actually, you'll mostly be using cargo and every so often you will want to use rustup to keep up-to-date.

rustup : The Rust Toolchain Manager

rustup is usually the first touchpoint with the Rust toolchain. It installs all and updates all the components of the toolchain, including updating itself. It also manages the different Rust toolchains you have installed (you can have more than one).

First time installation

See https://rustup.rs

Basically a curl command to download the rustup installer, and from then on... you're booted!

Updating

You can check for updates using rustup check:

% rustup check
stable-x86_64-apple-darwin - Update available : 1.52.1 (9bc8c42bb 2021-05-09) -> 1.57.0 (f1edd0429 2021-11-29)
rustup - Update available : 1.24.2 -> 1.24.3

Cool! There's an update available. Let's update!

% rustup update
info: syncing channel updates for 'stable-x86_64-apple-darwin'
info: latest update on 2021-12-02, rust version 1.57.0 (f1edd0429 2021-11-29)
info: downloading component 'rust-src'
info: downloading component 'cargo'
info: downloading component 'clippy'
info: downloading component 'rust-docs'
info: downloading component 'rust-std'
 23.6 MiB /  23.6 MiB (100 %)  23.2 MiB/s in  1s ETA:  0s
info: downloading component 'rustc'
 63.3 MiB /  63.3 MiB (100 %)  23.2 MiB/s in  2s ETA:  0s
info: downloading component 'rustfmt'
info: removing previous version of component 'rust-src'
info: removing previous version of component 'cargo'
info: removing previous version of component 'clippy'
info: removing previous version of component 'rust-docs'
info: removing previous version of component 'rust-std'
info: removing previous version of component 'rustc'
info: removing previous version of component 'rustfmt'
info: installing component 'rust-src'
info: installing component 'cargo'
info: installing component 'clippy'
info: installing component 'rust-docs'
 17.9 MiB /  17.9 MiB (100 %)   5.2 MiB/s in  2s ETA:  0s
info: installing component 'rust-std'
 23.6 MiB /  23.6 MiB (100 %)  13.4 MiB/s in  1s ETA:  0s
info: installing component 'rustc'
 63.3 MiB /  63.3 MiB (100 %)  14.8 MiB/s in  4s ETA:  0s
info: installing component 'rustfmt'
info: checking for self-updates
info: downloading self-update

  stable-x86_64-apple-darwin updated - rustc 1.57.0 (f1edd0429 2021-11-29) (from rustc 1.52.1 (9bc8c42bb 2021-05-09))

info: cleaning up downloads & tmp directories

Well, that was easy!

cargo : The package manager

After rustup, the next thing you will probably use is cargo. cargo is a build tool, a package manager, and a very basic project template tool.

Most people will want to create a new project to verify that the toolchain was installed correctly. Enter cargo new, described in the next seciton.

cargo new : Creating a new project

The cargo new command will create a simple 'Hello world!' program with all the appropriate files.

% cargo new my-new-project
    Created binary (application) `my-new-project` package

We can see that cargo created a new directory, with some files in it:

% cd my-new-project
% ls -R1
Cargo.toml
src

./src:
main.rs

• Cargo.toml - This metadata file tells cargo about the project. In this case, it's a simple "binary (application)". This is Rust-speak for a command line application.
• src/main.rs - The hello world code. With cargo, you can make packages with multiple command line applications (binaries), libraries, or any combination of these. When you are starting out, it's best to keep things simple and just have a single command line executable.

cargo run : Run the program

The cargo run command will:

• Compile the package, if it isn't already compiled.
• Run any tests.
• If all that succeds, launch the binary (command line program).

With a fresh "hello world" project generated with cargo new, this is pretty simple. Assuming we're in the my-new-project directory already:

% cargo run  
   Compiling my-new-project v0.1.0 (/Users/josh/git/rust-examples1/my-new-project)
    Finished dev [unoptimized + debuginfo] target(s) in 10.42s
     Running `target/debug/my-new-project`
Hello, world!

Wait, that's it?

Yup! There are other tools in the Rust toolchain, but most of the time you will probably interact with them via cargo. At this point you can start development.

There are other aspects of packaging up the binaries / libraries etc., but for basic development this is all you need. I'll cover how to publish / deploy various kinds of packages in follow up posts.

The Details

So, under the hood cargo orchestrates the other tools in the toolchain:

• rustc - The Rust compiler.
• clippy - A static analyzer / lint tool.
• The standard Rust library
  • rust-std - The standard Rust library.
  • rust-src - The source for the standard Rust library.
• rls - Language server, used by IDEs (I used CLion in my previous post)
• rust-docs - A documentation generator, like Javadoc, etc. Generates documentation from the source code.

More Details

For more details see:

• The rustup Book
• The cargo Book