Getting Started with Rust

This chapter walks you from a fresh machine to a running Rust program. Along the way you will see how a Cargo project is laid out and how to set up an editor that makes the compiler feel like a helpful pair programmer rather than a gatekeeper.

Installing with rustup

The recommended way to install Rust is rustup, the official toolchain manager. One install gives you the compiler (rustc), the build tool and package manager (cargo), the standard library, the formatter (rustfmt) and the linter (clippy). rustup also handles upgrades later on.

On macOS and Linux, run:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

On Windows, download and run rustup-init.exe from rustup.rs. The default Windows toolchain links with MSVC, so you also need the C++ build tools from Visual Studio Build Tools; the installer will point you to them if they are missing.

Open a new terminal afterwards and confirm everything is on your PATH:

rustc --version
cargo --version

# Upgrade to the latest stable release at any time
rustup update

# Included in the default profile, but easy to add if missing
rustup component add rustfmt clippy

Rust ships on three channels: stable, beta and nightly. Stable is the right choice for nearly everything. If you ever need an unstable feature, install nightly alongside it with rustup toolchain install nightly. To pin a toolchain for one project only, commit a rust-toolchain.toml file at the project root.

Creating a project with cargo new

Almost every Rust project starts with Cargo. cargo new creates the directory, a manifest, a starter source file, and even initializes a Git repository.

cargo new hello
cd hello

# Use --lib for a library instead of an executable
cargo new my_utils --lib

Cargo.toml is the manifest: name, version, edition and dependencies. An edition is a bundle of language-level changes that a crate opts into; recent versions of Cargo default to the newest edition.

[package]
name = "hello"
version = "0.1.0"
edition = "2024"

[dependencies]

src/main.rs holds the main function, the entry point of the program. Note the exclamation mark in println!: it marks a macro, not a regular function call.

fn main() {
    println!("Hello, world!");
}

Building and running

These are the Cargo commands you will reach for daily:

Make cargo check a habit while you code. It skips code generation, so it is much faster than a full build. When you measure performance, always use --release: unoptimized debug builds can be dramatically slower.

Arguments for your program go after --. Put the following in src/main.rs and try cargo run -- Alice Bob:

use std::env;

fn main() {
    // The first argument is the program path, so skip it
    let names: Vec<String> = env::args().skip(1).collect();

    if names.is_empty() {
        println!("Pass one or more names as arguments.");
        return;
    }

    for name in &names {
        println!("Hello, {name}!");
    }
}

Project layout

Cargo relies on conventions, so files placed in the expected spots are picked up with zero configuration:

• Cargo.toml: package metadata and dependencies
• Cargo.lock: exact resolved dependency versions (generated; commit it for applications)
• src/main.rs: entry point of a binary crate
• src/lib.rs: root of a library crate (a package may have both)
• src/bin/*.rs: additional binaries, one per file
• tests/: integration tests
• examples/: runnable examples via cargo run --example name
• target/: build output, keep it out of version control

Setting up your editor

The heart of a good Rust setup is rust-analyzer, the language server. It powers completion, inline type hints, go-to-definition and refactorings. In VS Code, install the rust-analyzer extension published by rust-lang. RustRover from JetBrains, Zed, and Neovim with an LSP client are popular alternatives.

To format on save and run clippy instead of plain cargo check in VS Code, add this to settings.json:

{
  "[rust]": {
    "editor.formatOnSave": true
  },
  "rust-analyzer.check.command": "clippy"
}

If your team wants different formatting rules, drop a rustfmt.toml in the project root. Most projects stick with the defaults, which keeps code looking the same across the whole ecosystem.

max_width = 100

Summary

• rustup installs and updates rustc, cargo, rustfmt and clippy in one go.
• cargo new scaffolds a project and cargo run builds and runs it.
• Use cargo check for fast feedback and cargo build --release for anything performance-related.
• Install rust-analyzer and let your editor run rustfmt and clippy for you.