The following guide will walk you through creating your first Rust project using Cargo, Rust's package manager and build system. Cargo handles many tasks, including building your code, downloading dependencies, and building those dependencies.

Prerequisites

  • Rust installed on your system (follow the Rust installation guide if you haven't installed it yet)
  • Basic familiarity with command-line operations

Step 1: Verify Cargo Installation

First, let's ensure Cargo is properly installed:

  1. Open your terminal or command prompt
  2. Run the following command: 
cargo --version
  1. You should see output similar to: 
cargo 1.xx.x (abcdefg 20xx-xx-xx)

If you don't see this output, you may need to reinstall Rust, as Cargo comes bundled with Rust.

Step 2: Create a New Project

Now, let's create your first Rust project:

  1. Navigate to where you want to create your project: 
cd ~/projects    # On Linux/macOS
   cd %USERPROFILE%\projects    # On Windows CMD
   cd ~/projects    # On Windows PowerShell
  1. Create a new project using Cargo: 
cargo new hello_world
  1. You should see output similar to: 
Created binary (application) `hello_world` package

This command creates a new directory called hello_world with the following structure:

hello_world/
├── Cargo.toml
└── src/
    └── main.rs

Step 3: Understand the Project Structure

Let's examine what Cargo created:

  • Cargo.toml: This is your project's configuration file, similar to package.json in Node.js. It contains metadata about your project and its dependencies.
  • src/main.rs: This is your project's source code file, containing a simple "Hello, world!" program.

The Cargo.toml File

Open Cargo.toml. It should look something like this:

[package]
name = "hello_world"
version = "0.1.0"
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]

This file contains:

  • Project metadata (name, version, edition)
  • A section for dependencies (currently empty)

The main.rs File

Open src/main.rs. It should contain this code:

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

This is a simple Rust program that prints "Hello, world!" to the console.

Step 4: Build Your Project

Now let's build the project:

  1. Navigate to your project directory (if you're not already there): 
cd hello_world
  1. Build the project with Cargo: 
cargo build
  1. You should see output indicating the build process. When it completes, your project will be compiled and ready to run.

This command creates an executable in the target/debug directory.

Step 5: Run Your Project

You can run your project in two ways:

Option 1: Use the compiled executable

After building, you can run the executable directly:

# On Linux/macOS
./target/debug/hello_world

# On Windows
.\target\debug\hello_world.exe

Option 2: Use Cargo to build and run (recommended)

Cargo provides a convenient command to build and run your project in one step:

cargo run

This command compiles your code if changes are detected and then runs the executable.

You should see the output:

Hello, world!

Step 6: Modify Your Project

Let's make a simple change to your program:

  1. Open src/main.rs in your text editor
  2. Change the message to something else: 
fn main() {
       println!("Hello, Rust programmer!");
   }

  1. Save the file

  2. Run the program again:

cargo run

You should now see your new message:

Hello, Rust programmer!

Step 7: Check Your Code

Cargo provides a command to check your code for errors without building it:

cargo check

This is often faster than cargo build and useful during development to quickly verify your code compiles.

Step 8: Release Build

When you're ready to create an optimized version of your program:

cargo build --release

This creates an optimized executable in the target/release directory, which runs faster but takes longer to compile.

Step 9: Add Dependencies

Let's add a simple dependency to your project:

  1. Open Cargo.toml in your text editor
  2. Add a dependency in the [dependencies] section: 
[dependencies]
   rand = "0.8.5"
  1. Update your src/main.rs to use this dependency: 
use rand::Rng;

   fn main() {
       println!("Hello, Rust programmer!");

       let secret_number = rand::thread_rng().gen_range(1..101);
       println!("I'm thinking of a number between 1 and 100: {}", secret_number);
   }
  1. Run your program: 
cargo run

Cargo will automatically download and compile the rand dependency before building your project.

Common Cargo Commands

Here's a summary of essential Cargo commands:

  • cargo new : Create a new project
  • cargo build: Build your project
  • cargo run: Build and run your project
  • cargo check: Check your code for errors without building
  • cargo build --release: Build with optimizations for release
  • cargo update: Update dependencies
  • cargo doc --open: Generate and open documentation for your project and all dependencies

Next Steps

Now that you've created your first Rust project, you can:

  1. Explore the Rust Book to learn more about Rust programming
  2. Create a more complex project, such as a guessing game
  3. Experiment with other Rust libraries by adding them to your dependencies
  4. Learn about Rust's ownership system, which is one of its most distinctive features

Congratulations on creating your first Rust project with Cargo!