The Rust Programming Language Command Line Tools

By Dr. Saad Laouadi

About the Book

The Rust programming language has rapidly gained popularity for its performance, reliability, and productivity. As a systems programming language, Rust provides the control and efficiency needed for developing robust and scalable applications. It's essential to become proficient in the command line tools that accompany Rust in order to fully utilize these capabilities.

This book provides a comprehensive guide to the essential Rust command line tools, including rustup, cargo, and rustdoc. The objective of this book is to be sufficiently detailed to benefit individuals with little or no programming experience. The syntax has been simplified to alleviate the apprehension often associated with using command line tools or terminals, as many individuals prefer to rely on Integrated Development Environments (IDEs). Therefore, this book serves a dual purpose: facilitating the adaptation to command line interface (CLI) applications while mastering Rust CLI utilities. Consequently, readers will be equipped to efficiently manage Rust projects, handle dependencies, build and document code, and ensure smooth workflows.

Preface

The Rust programming language has rapidly gained popularity among developers for its performance, reliability, and memory safety. To maximize the potential of Rust, it is essential to master the command line tools that are integral to the Rust development workflow. This book is dedicated to providing an in-depth understanding of these tools, including rustup, cargo, and rustdoc. This book aims to equip you with the knowledge and skills needed to efficiently manage your Rust projects.

Who This Book Is For

This book is designed for:

Beginners: Individuals who are new to Rust and want to understand how to use its command line tools effectively.
Experienced Developers: Programmers with experience in Rust who seek to deepen their knowledge and optimize their workflow.
Students and Educators: Learners and teachers looking for a comprehensive resource on Rust command line tools.
Project Managers and Team Leads: Professionals who need to manage Rust projects and ensure smooth collaboration among team members.

Introduction

The Rust programming language is known for its performance, reliability, and productivity. To fully harness these advantages, it's crucial to master the command line tools that accompany Rust. This book provides a comprehensive guide to the most essential Rust command line tools: rustup, cargo, and rustdoc. Whether you are a beginner or an experienced developer, this book will help you efficiently manage your Rust projects, handle dependencies, build and document your code, and ensure smooth workflows.

How to Use This Book

This book is structured to provide both theoretical knowledge and practical application. Each section includes detailed explanations, examples, and exercises to help reinforce your understanding of the material.

Structure of the Book

Rust Toolchain: Rustup:
- Overview of Rustup
- Installing Rust with Rustup
- Managing Rust Toolchains
- Updating Rust
- Using Custom Toolchains
- Configuring Rustup
- Common Rustup Commands
Rust Package Manager: Cargo:
- Overview of Cargo
- Creating a New Project
- Building Projects
- Running Projects
- Managing Dependencies
- Testing
- Generating Documentation
- Publishing Crates
- Cargo Workspaces
- Advanced Cargo Features
- Common Cargo Commands
Rust Documentation Tool: Rustdoc:
- Overview of Rustdoc
- Writing Documentation Comments
- Generating Documentation with Rustdoc
- Documenting Code Examples
- Using Rustdoc Attributes
- Hosting Documentation
- Common Rustdoc Commands
Appendices:
- Useful Rust Resources
- Common Issues and Troubleshooting
- Glossary

Conventions Used in This Book

Code Blocks: Code snippets and examples are presented in monospace font.

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

Commands: Command line commands are prefixed with $ to indicate the shell prompt.
```
$ cargo build
```
Tips and Notes: Additional information and tips are provided in block quotes.

Tip: Use cargo check to quickly check your code for errors without producing an executable.

About the Author

This book is authored by Dr. Saad Laouadi, a data scientist, programmer and a researcher with extensive experience in the programming, machine learning and artificial intelligence. Dr. Saad aims to provide readers with valuable insights and practical guidance on mastering Rust command line tools.

Acknowledgments

Special thanks to the Rust community for their continuous support and contributions to the development of Rust and its ecosystem. This book would not have been possible without the collaborative efforts of developers, educators, and enthusiasts who have shared their knowledge and expertise.

Getting Started

To get started with the Rust command line tools, proceed to the first chapter on Rustup, where you will learn how to install and manage Rust toolchains effectively.

Overview of Rustup

Rustup is the official Rust toolchain installer, and it allows you to manage multiple versions of Rust and associated components.

Getting Help

rustup --help

Here is the output from the previous command:

The Rust toolchain installer

Usage: rustup [OPTIONS] [+toolchain] [COMMAND]

Commands:
  show         Show the active and installed toolchains or profiles
  update       Update Rust toolchains and rustup
  check        Check for updates to Rust toolchains and rustup
  default      Set the default toolchain
  toolchain    Modify or query the installed toolchains
  target       Modify a toolchain's supported targets
  component    Modify a toolchain's installed components
  override     Modify toolchain overrides for directories
  run          Run a command with an environment configured for a given toolchain
  which        Display which binary will be run for a given command
  doc          Open the documentation for the current toolchain
  man          View the man page for a given command
  self         Modify the rustup installation
  set          Alter rustup settings
  completions  Generate tab-completion scripts for your shell
  help         Print this message or the help of the given subcommand(s)

Arguments:
  [+toolchain]  release channel (e.g. +stable) or custom toolchain to set override

Options:
  -v, --verbose  Enable verbose output
  -q, --quiet    Disable progress output
  -h, --help     Print help
  -V, --version  Print version

Getting Rustup Version

rustup --version

General Syntax

rustup <COMMAND> [OPTIONS] <ARGUMENTS>

Rustup toolchain

The general Syntax is:

rustup toolchain <COMMAND>

rustup toolchain help

Here is some output from the previous command:

Modify or query the installed toolchains

Usage: rustup toolchain <COMMAND>

Commands:
  list       List installed toolchains
  install    Install or update a given toolchain
  uninstall  Uninstall a toolchain
  link       Create a custom toolchain by symlinking to a directory
  help       Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

Getting Help for `rustup toolchain` Subcommands

rustup toolchain <SUB-COMMAND> HELP

for example, if you needed to get help for the list subcommand, you would have typed this command:

rustup toolchain list --help

Rustup Toolchain list

This command lists the installed toolchains

rustup toolchain list

you can print more information by using the -v or --verbose option.

Rustup toolchain

Installing Rust with Rustup

Showing Installed toolchains

rustup show

rustup show --help

Show the active and installed toolchains or profiles

The general syntax:

rustup show [OPTIONS] [COMMAND]

Commands:
  active-toolchain  Show the active toolchain
  home              Display the computed value of RUSTUP_HOME
  profile           Show the default profile used for the `rustup install` command
  help              Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose  Enable verbose output with rustc information for all installed toolchains
  -h, --help     Print help

Discussion:
    Shows the name of the active toolchain and the version of `rustc`.

    If the active toolchain has installed support for additional
    compilation targets, then they are listed as well.

    If there are multiple toolchains installed then all installed
    toolchains are listed as well.

Examples

rustup show -v home

/Users/username/.rustup

rustup show -v active-toolchain

stable-x86_64-apple-darwin (default)

rustup show -v profile

default

Managing Rust Toolchains

Checking for Updates

Updating Rust

The `update` Command

Update Rust toolchains and rustup

rustup update --help

The general syntax:

rustup update [OPTIONS] [toolchain]...

Arguments:
  [toolchain]...  Toolchain name, such as 'stable', 'nightly', or '1.8.0'. For more
                  information see `rustup help toolchain`

Options:
      --no-self-update  Don't perform self update when running the `rustup update` command
      --force           Force an update, even if some components are missing
      --force-non-host  Install toolchains that require an emulator. See
                        https://github.com/rust-lang/rustup/wiki/Non-host-toolchains
  -h, --help            Print help

Discussion:
    With no toolchain specified, the `update` command updates each of
    the installed toolchains from the official release channels, then
    updates rustup itself.

    If given a toolchain argument then `update` updates that
    toolchain, the same as `rustup toolchain install`.

Using Custom Toolchains

Listing Installed Toolchains:

To see a list of all installed toolchains, you can use:

rustup toolchain list

Install a Specific Toolchain:

If you need to install a specific toolchain, you can use:

rustup toolchain install <toolchain>

For example, to install the nightly toolchain:

rustup toolchain install nightly

Configuring Rustup

Common Rustup Commands

The Rustup Default Command

The rustup default command is used to set or query the default Rust toolchain for the current user.

Getting Help

rustup default --help

The general syntax

rustup default [toolchain]

Usage: rustup default [toolchain]

Arguments:
  [toolchain]  'none', a toolchain name, such as 'stable', 'nightly', '1.8.0', or a custom toolchain name.
               For more information see `rustup help toolchain`

Options:
  -h, --help  Print help

Discussion:
    Sets the default toolchain to the one specified. If the toolchain
    is not already installed then it is installed first.

Basic Usage

Query the Default Toolchain: Running the command without any arguments will display the current default toolchain.
Set the Default Toolchain: You can set a specific toolchain as the default by providing the toolchain name as an argument.

Querying the Default Toolchain

To see which toolchain is currently set as the default, you can simply run:

rustup default

This command will output the name of the default toolchain, for example, here is an output from my machine:

stable-x86_64-apple-darwin (default)

Setting the Default Toolchain

Before you set a default toolchain, you may want to list the installed toolchains in your machine. For more details on listing installed toolchains, refer to the Custom Toolchains section.
To set a specific Rust toolchain as the default, you can specify the toolchain name. For example, if you want to set the stable toolchain as the default, you would use:

rustup default stable

If you want to set the nightly toolchain as the default, you would use:

rustup default nightly

Example: Setting the Default Toolchain to Stable

Set the Default Toolchain:

rustup default stable

Verify the Default Toolchain:

rustup default

stable-x86_64-unknown-linux-gnu (default)

Setting the Default Toolchain to Nightly

Set the Default Toolchain:

rustup default nightly

Verify the Default Toolchain:

rustup default

nightly-x86_64-unknown-linux-gnu (default)

Use Case: Creating Rust Application with Rust Edition 2024

On my current version of Rust installed on my machine 1.78, using Rust edition 2024 is not allowed, thus we need to set the default toolchain to nightly

Setting the nightly toolchain

If the toolchain is not installed, then rustup will install it first and then set it to be the default for our projects.

rustup default nightly

Check the default now

rustup default

Create the rust application with Rust edition 2024

cargo new test_app --edition 2024 --name test-application

Check the application

cd test_app
cargo check

Here is the Cargo.toml file

[package]
name = "test-application"
version = "0.1.0"
edition = "2024"

[dependencies]

Checking the application

cargo check

This command issued an error like this:

error: failed to parse manifest at `~/test_app/Cargo.toml`

Caused by:
  feature `edition2024` is required

  The package requires the Cargo feature called `edition2024`, but that feature is not stabilized in this version of Cargo (1.81.0-nightly (b1feb75d0 2024-06-07)).
  Consider adding `cargo-features = ["edition2024"]` to the top of Cargo.toml (above the [package] table) to tell Cargo you are opting in to use this unstable feature.
  See https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#edition-2024 for more information about the status of this feature.

So I need to add cargo-features = ["edition2024"] to the Cargo.toml as suggested by the compiler

Here is the updated file:

cargo-features = ["edition2024"]
[package]
name = "test-application"
version = "0.1.0"
edition = "2024"

[dependencies]

Now checking the application again using cargo check command.
The application passed and it is working fine.

Checking test-application v0.1.0 (~/test_app)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.36s

If you need to set the stable version for other projects, it suffices to use the next command:

rustup default stable

Check to make sure

rustup default

Overall, you will be familiar with commands and they will become natural to you as you work with different types of Rust applications.

The rustup default command streamlines the management of the default Rust toolchain on your system. It allows for convenient switching between different Rust versions to meet your development requirements, such as:

stable.
beta.
nightly.

Setting the correct default toolchain guarantees that your development environment is configured accurately for your projects.

Rust Command Line Tools