Rust tutorial: Get started with the Rust language

Over the last few years, Rust has evolved from a curiosity brewed up in a Mozilla employee’s lab to a strong contender for the next generation of system-native applications and bare-metal solutions. Those advances come from Rust providing its own toolchain and component management system—along with certain popular features and quirks.

This article is for developers new to Rust or considering it for future projects. We’ll walk through setting up a working environment in Rust, configuring an IDE, and making the most of Rust’s excellent application development toolset.

Understanding Rust releases

Rust’s toolchain consists of two key tools: rustup, a tool for keeping Rust itself up to date, and the Rust compiler, rustc. Because Rust is under constant development, its toolchain is designed to be easy to update.

Software projects are often provided via multiple release channels to keep the stable and beta versions of the code separate. Rust works the same way, offering three channels for toolchain updates:

Stable: Major point releases, which emerge every six weeks or so.

Beta: Candidates for the next major point release, which emerge more frequently.

Nightly: The most immediate build, with access to cutting-edge features but no guarantees as to their stability.

As developer Karol Kuczmarski has pointed out, it’s best to think of the nightly Rust release as its own language. Some Rust features are only available in nightly Rust, and they can only be activated by special compiler directives. In other words, they won’t even compile on the beta or stable release channels.

There’s no guarantee the nightly features will be supported anywhere else, or ever again. However, many features eventually graduate out of the nightly channel and into beta and stable releases. (Compiling to WebAssembly, for instance, works in the stable version as of Rust 1.30.)

What does this mean for you as a developer? In short:

Use a stable release for actual production work.

Use beta releases to test current software against upcoming versions to see if anything may break in the upgrade.

Only use nightly releases for sandboxed experiments with Rust’s newest features.

Choosing your Rust development platform

Rust supports all three major operating systems—Windows, Linux, and macOS—in both 32- and 64-bit incarnations, with official binaries for each. All three platforms are also supported on ARM64 processors.

A slew of other platforms also have official binaries, but they don’t have the same level of automated test coverage. These second-class platforms include ARMv6 and ARMv7 for iOS, Android, and Linux; MIPS Linux and MIPS64 Linux; 32-bit editions of x86 iOS, Windows, and Linux; and WebAssembly. Other platforms, like Windows XP or the experimental HaikuOS, are supported through unofficial builds.

Rust’s development team has stated that being broadly portable isn’t one of Rust’s missions. For example, although Rust is available on many ARM architectures, there is no guarantee that it will be officially supported on low-end hardware platforms.

That said, you should be able to find a supported Rust build for most common, mainstream use cases—namely, 32- and 64-bit Windows, Linux, and macOS.

Rust on Windows

If you’re planning to develop in Rust on Windows, keep your toolchains in mind. Rust supports two Windows toolchains:

The native Microsoft Visual C (MSVC) ABI

The Gnu ABI used by the GCC linker

Because almost all C/C++ software built in Windows uses MSVC anyway, you’ll want to use the MSVC toolchain most of the time. If you ever need GCC, it’ll most likely be for interoperating with third-party libraries built in Windows with GCC.

The good news is that Rust’s toolchain management system lets you keep both MSVC and GCC toolchains installed, and it lets you switch between them on a project-by-project basis.

Rust with WebAssembly

One of Rust’s compilation targets is WebAssembly, which lets you write in Rust and deploy to a web browser. WebAssembly itself is still rough around the edges, and so is Rust’s support for it. But if you’re ambitious and you want to get your hands messy, this guide details the process for compiling WebAssembly to Rust. Written by Rust and WebAssembly engineers, the book includes many real-world example scenarios, such as working with a canvas object in a browser, WebSockets, audio, and Web Workers.

Setting up the Rust toolchain

Rust provides an all-in-one installer and toolchain maintenance system called rustup. Download rustup and run it; it’ll obtain the latest versions of the Rust toolchain and install them for you.

The most critical tools maintained by rustup are:

rustup itself: Whenever new versions of rustup or other tools are published, you can just run rustup update and everything will be updated automatically.

rustc: The Rust compiler.

Cargo: Rust’s package and workspace manager.

By default, rustup installs Rust from the stable release channel. If you want to use a beta or nightly version, you must install those channels manually (for example, by running rustup install nightly) and set Rust to use them by default (rustup default nightly). You can also manually specify which channel to use when compiling a Rust application, so you don’t have to set and reset the default every time you move between projects.

The rustup utility keeps all parts of your Rust toolchain updated to their most recent versions. Here, the nightly toolchain, with bleeding-edge and potentially unstable language components, is being updated separately from the stable version.Foundry

You can also use rustup to install and maintain custom toolchains. These are typically used by unofficial, third-party builds of Rust for unsupported platforms, which usually require their own linkers or other platform-specific tools.

Another default assumption of Rust is that it stores Cargo files—the downloaded packages and configuration information—in a subdirectory of your user profile. In some cases, you may want that data on another drive where there is more room, or in a place that is more accessible. If you want Cargo to live somewhere else, you can relocate it manually after the setup is finished. Here are the steps:

Close down all programs that might be using Cargo.

Copy the.cargo directory in your user profile to where you want it to live.

Set the environment variables CARGO_HOME and RUSTUP_HOME to point to the new directory.

Set the PATH to point to the bin subdirectory of the new directory.

Type cargo to ensure Cargo is running properly.

Configuring your IDE for Rust

Despite Rust being a relatively new language, it’s already garnered strong support from many common IDEs. Developer Manuel Hoffman maintains a project to track the state of such support at the website areweideyet.com.

Making Rust work well with IDEs is an express goal of its development team, via a feature called the Rust Language Server (RLS). RLS provides live feedback about the code in question from Rust’s own compiler, rather than from a third-party parser.anguage Server (RLS). RLS provides live feedback about the code in question from Rust’s own compiler, rather than from a third-party parser.

Rust’s Language Server project provides live feedback to an IDE from the Rust compiler for the code you’re working with. Visual Studio Code, shown here, has some of the most complete support available for RLS.
Foundry

Here are the IDEs that support Rust as of this writing:

Microsoft’s Visual Studio Code has a Rust language support extension created by Rust’s own developer tools team. This level of integration makes it one of the best-supported IDEs for Rust.

Eclipse users can download a prepackaged edition of Eclipse for Rust development, or use the standalone Corrosion plugin for Eclipse Photon. However, neither have been updated since 2022.

If you’re a fan of Emacs or Vim, other developers like you have written Rust-specific add-ons for both editors. Emacs has a Rust-specific mode, and Vim has a plugin to provide syntax highlighting and formatting. RLS support is available for both Emacs and Vim, but you must add and configure it manually.

JetBrains has its own dedicated Rust IDE, RustRover.

Sublime Text has Rust syntax support out of the box, and plugins provide deeper support for other features.

Creating your first Rust project

Rust projects are meant to have a consistent directory structure, with code and project metadata stored within them in certain ways. Code is stored in a src subdirectory, and details about the project are stored in two files in the project’s root directory, Cargo.toml (the project’s basic information) and Cargo.lock (an automatically generated list of dependencies). You can create that directory structure and metadata by hand, but it’s easier to use Rust’s own tools to do the job.

Learn Rust
The Rust By Example online guide to learning Rust provides interactive code samples that can be edited and run directly in the browser. It touches on almost every major Rust concept, although some of the more key concepts, like borrowing and lifetimes, are introduced relatively late in the series.

Rust’s Cargo tool manages both Rust projects and the libraries, or “crates,” they use. To spin up a new Rust project named my_project in its own directory, type cargo new my_project. (For C# developers working with.Net Core, think of the dotnet new command.) The new project appears in a subdirectory with that name, along with a basic project manifest—the Cargo.toml file—and a stub for the project’s source code, in a src subdirectory.

When you create a new project, a main.rs file is automatically created in the project’s src directory. This file contains a basic “hello world” application, so you can test out your Rust toolchain right away by compiling and running it.

Here’s the source code for that basic “hello world” application:

fn main() {
println!(“Hello World!”);
}

To build and run the application, go to the project directory’s root and type cargo run. Note that by default, Cargo builds projects in debug mode. To run in release mode, use cargo run --release, or cargo run -r. Binaries are built in the project’s target/debug or target/release subdirectory, depending on which compilation profile you’re using.

When a Rust project is compiled, all its dependencies are obtained and compiled automatically, as well. Detailed line-by-line feedback appears for anything that raises a warning or error.
Foundry

Working with Rust crates

Package management is a key part of any modern programming environment. To that end, Rust provides “crates,” which are third-party libraries packaged for distribution with Rust’s tools. You can find crates in the official Rust package registry, Crates.io.

If your project has a dependency on a particular crate, you need to specify that crate by editing the project’s Cargo.toml file. The standard way to do this is manually—that is, by simply editing Cargo.toml directly with a text editor. The next time the project is rebuilt, Rust automatically obtains any needed dependencies.

Updating dependencies
Two tools, cargo-edit and cargo-edit-locally, can update dependencies from the command line, although they are unofficial third-party projects. (Note that cargo-edit-locally has not been updated since 2017.)

When you build a Rust project that depends on external crates, Cargo looks for those crates on Crates.io by default; you don’t need to obtain them manually. You can also refer to crates in your project by URL rather than by crate name, in case you need a crate that isn’t hosted in the registry, such as something from a private repository.

Note that some crates will only install and build on Rust’s nightly channel, because they use experimental features not available in other channels. If you’re on the release channel and you try installing such a crate, you won’t get any warning until the compilation fails. Crate documentation usually mentions whether it requires the nightly channel or not, so read up before you include, let alone compile.

Crates can come with binaries included. Some are command-line tools used in Rust development; others are general-purpose tools (such as ripgrep). To install one of these crates, just type cargo install. This isn’t the only way to distribute a binary created with Rust, but it’s a convenient way for Rust developers to obtain them as part of a workflow involving Rust tools.

Cross-compiling Rust to another platform

Because Rust supports multiple toolchains, even in the same Rust installation, you can compile Rust applications to a target operating system and environment that’s different from the one you’re compiling on.

Such cross-compiling requires a toolchain on the platform you’re working on that matches the target platform. Sometimes, as with cross-compiling to Linux on Windows, or vice versa, this involves little more than having the GCC linker. But other times, it’s more complex. If you want to cross-compile to macOS, for example, you need the Xcode IDE libraries to finish the job—cctools (Apple’s equivalent of binutils) and the macOS SDK.

Some third-party tools can help you work around these difficulties:

Cross runs directly on a 64-bit x86 Linux host and provides what its creator describes as “zero-setup” cross-compiling to a wide variety of targets, including 64-bit Windows and MIPS.

Trust is a Travis CI and AppVeyor template that can automatically publish binary releases of a Rust project. Trust can build for Linux, Windows, and macOS, although it requires the Travis CI and AppVeyor services. Your project also must be hosted on GitHub.

The crossbuild project provides a multi-architecture Docker image that can be used to cross-build between all three major platforms.

Note that of these three tools, only Cross has been updated recently.

An easy way to get started with Rust

A good way to get your legs with Rust is to check out a third-party project and work on it locally. The easy way to do that is to make a Git clone of a Rust project’s repository. As long as the repo has a Cargo.toml file in its root, it’ll be recognized by Cargo.

One thing Cargo can’t do, at least not yet, is make a local clone of a crate by itself. This is possible with Git, and most anyone doing serious work with Rust should have Git installed anyway. But you can add that functionality to Cargo directly via the third-party Cargo subcommands cargo-clone and cargo-clone-crate.

Where can you find projects to tinker with and learn from? For starters, go to the Awesome Rust repository on GitHub. Some of the projects include:

The Servo web browser engine, one of Rust’s first intended real-world applications.

Microsoft’s Edit, a CLI-based editor with a modern UI.

The mdBook project, for generating online books and e-books from Markdown documents.

Many other projects are useful on their own merit, not only for getting a leg up with Rust or because they’re components of a larger effort. These include Hickory DNS (a DNS server and client), Alacritty (a GPU-enhanced terminal emulator), and the MaidSafe decentralized data platform. (For fun, check out the Bevy game engine, which has many example projects.)

Awesome Rust also lists many of the best crates and third-party tools to learn about and put to use.

If you’re hunting for a project to get involved with as a developer, try searching GitHub for Rust-based projects that have open issues tagged with “good-first-issue.” That tag indicates an issue that will be relatively easy for a new developer to help out with. It’s a great way to learn the ropes with Rust while helping out a project.