Skip to content

Setting up a dev container for Rust

Success

I have successfuly added admonitions to MkDocs!
This is just an example of admonitions you will see throughout this tutorial for the purpose side content without disturbing document flow :)

# I have added the code block extention for my partner - Mohammad Saatialsoruji
# Code blocks are an essential part of project documentation
# We will see these many times throughout the tutorial
print("We love COMP 423!")

Welcome

This tutorial will provide step-by-step instructions for creating a Development (Dev) Container in Rust.

Info

This tutorial is highly inspired by a previous tutorial my professor Kris Jordan had already made so you might see a lot of similarities and I would highly recommend you check his out!

Let's start with the prerequisites

Before we dive in, make sure you have the following if you don't already:

  1. A GitHub account: Sign up at GitHub.
  2. Git installed: Install Git.
  3. Visual Studio Code (VS Code): Download and install VSCode.
  4. Docker installed:Get Docker here. This is required to run the container.

Note

For this tutorial, you do not need to install anything other than VSCode, Docker, and Git. You should not install Rust. That is the role of the dev container! Remember, we are trying to minimize the things we have to manually download and install. I will say, though, you should be comfortable and have a little bit of command line knowledge. Your 211 knowledge should serve you well here!

Part 1: Project setup (Setting up your directory, Git, and GitHub)

Step 1: Creating a directory and a local Git Repository

  • Open your terminal or command prompt.
  • Create a new directory: 
    mkdir rust-dev-cont
cd rust-dev-cont
  • Initialize a new Git repository 
    git init
  • Create a README file and add the following: 
    echo "# Building a Dev Container in Rust" > README.md
git add README.md
git commit -m "Initial commit with README"

Note

The command echo sends the string in quotation marks to the specified place. Usually without any place to go, it just sends it back to stdout which is your terminal by default. However, if you have taken 211 before, you know that the > operator writes whatever is on the left of it (which could be the output of a program) to the specified place on the right. If the file does not exist already, it creates it.

Step 2: Creating a remote repository

  1. Log in to your GitHub account and navigate to the Create a New Repository page.
  2. Fill in the details as follows:
    • Repository Name: rust-dev-cont
    • Description: "Personal project for starting a Dev Container in Rust"
    • Visibility: Public
  3. Do not initialize the repository with a README, .gitignore, or license.
  4. Click Create Repository.
  1. Add the GitHub repository as a remote: 
    git remote add origin https://github.com/<your-username>/rust-dev-cont.git
    Replace <your-username> with your GitHub username.

  2. Check your default branch name with the subcommand git branch. If it's not main, rename it to main with the following command: git branch -M main. Old versions of git use the name master for the primary branch. However, main is the standard primary branch name ever since 2020.

  3. Push your local commits to the GitHub repository: 

    git push --set-upstream origin main

Note

git push --set-upstream origin main: This command pushes the main branch to the remote repository origin (Usually, the default name given to the remote repository). The --set-upstream flag sets up the main branch to track the remote branch origin/main, meaning future pushes and pulls can be done without specifying the branch name and just writing git push origin (or just git push if you only have one remote) when working on your local main branch. This long flag has a corresponding -u short flag that you can use as you are more comfrotable with working with flags.

You can now refresh your GitHub repository in your browser to see that the same commit you made locally has now been pushed to remote. You can also use git log locally to see the commit ID and message which should match the ID of the most recent commit on GitHub.

Part 2: Setting up the Development Environment

Before you begin developing in Rust, you need to set up your development environment!

What is a Development (Dev) Container?

In essence, a dev container is a preconfigured environment defined by a set of configuration files usually using Docker to create isolated setups for development. You can think of it as a mini computer running inside your computer that includes everything you need to work on a specific project. Your dev container will include the right programming language, tools, libraries and dependencies. This is why you don't need to install Rust for the purpose of this tutorial. The dev container ensures that your development environment is consistent and works across different machines.

Why is this valuable?

In the tech industry, teams often work on complex projects that require a specific set of tools and dependencies to function correctly. Without a dev container, each developer must manually set up their environment. You can only imagine how much it can lead to errors, wasted time, and inconsistencies. With a dev container:

  • Everyone works in an identical environment, reducing bugs caused by "it works on my machine" issues.
  • Onboarding new team members becomes faster and easier, as they can start coding with just a few steps.
  • Dependencies and tools remain isolated, avoiding conflicts with other projects or the local system.
  • A container also uses the same image everytime it is ran which means if you modify something in the image or accidentally delete something, a simple reboot of the container will fix everything and save you much pain :)

How are Software Project Dependencies Managed?

To effectively manage software dependencies, it's important to use a reliable package manager. Dependencies are external libraries or tools that your project relies on, and managing them ensures your project uses the correct versions, avoiding compatibility issues.

Dependency Management in Rust

In Rust, dependencies are managed using Cargo, the package manager and build system. Cargo automates tasks like:

  1. Declaring Dependencies: Dependencies are specified in the Cargo.toml file.
  2. Installing Dependencies: Cargo fetches and installs the required libraries from crates.io.
  3. Ensuring Consistency: The Cargo.lock file ensures that all team members use the exact same dependency versions.

For example, in the Cargo.toml file: 

[dependencies]
serde = "1.0"
We will see an example of this later on!

Step 1: Add Development Container Configuration

  1. In VS Code, open the rust-dev-cont directory. You can do this via: File > Open Folder.
  2. Install the Dev Containers extension for VS Code.
  3. Create a .devcontainer directory in the root of your project with the following file inside of this "hidden" configuration directory:

.devcontainer/devcontainer.json

Want a Shortcut to Open Projects in VS Code?

For more convenience, you can set up the code command in your terminal, allowing you to open projects directly from the command line.
Check out my tutorial here!

The devcontainer.json file defines the configuration for your development environment. Here, we're specifying the following:

  • name: A descriptive name for your dev container.
  • image: The Docker image to use, in our case, the latest version of a Rust environment. Microsoft maintains a collection of base images for many programming language environments, but you can also create your own!
  • customizations: Adds useful configurations to VS Code, like installing the Rust Analyzer extension. When you search for VS Code extensions on the marketplace, you will find the string identifier of each extension in its sidebar (e.g. rust-lang.rust-analyzer). Adding extensions here ensures other developers on your project have them installed in their dev containers automatically. Remember, we are trying to get rid of manually installing a bunch of software.
  • postCreateCommand: A command to run after the container is created. In our case, we do not need to install anything extra for us to print a simple string in Rust. 
    {
  "name": "My Rust Dev Container",
  "image": "mcr.microsoft.com/devcontainers/rust:latest",
  "customizations": {
    "vscode": {
      "settings": {},
      "extensions": ["rust-lang.rust-analyzer"]
    }
  },
  "postCreateCommand": ""
}

Step 2. Reopen the Project in a VSCode Dev Container

Reopen the project in the container by pressing Ctrl+Shift+P (or Cmd+Shift+P on Mac), typing "Dev Containers: Reopen in Container," and selecting the option. This will take a few minutes for the first time to download and install the image and everything.

Once your dev container setup completes, open a new terminal pane within VSCode, and try running rustc --version to see your dev container is running a recent version of Rust without you having to even manually download or install anything! (As of January 2025, the latest stable Rust version is 1.83.0.) The latest keyword in the image specification should take care of making sure you have the latest version!

Part 3: Developing in Rust

Creating a New Package

To start a new package with Cargo, use cargo new: 

cargo new hello_world --vcs none
The --vcs none flag tells cargo to not create a git repository for you which is the default behavior.

Warning

If you forgot the --vcs none flag, it's no problem. You can run the following commands to delete the Git repository.

cd hello_world
rm -rf .git
This removes the Git repository from the project while keeping the project files.

Let's check out what Cargo has created:

Run the following commands: 

cd hello_world
tree
The output should be something like: 
.
├── Cargo.toml
└── src
    └── main.rs

2 directories, 2 files
You can checkout the Cargo.toml in VSCode to see something like this (Hint: this is what we talked about up there ^^^):

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

[dependencies]
This is called a manifest, and it contains all of the metadata that Cargo needs to compile your package. This file is written in the TOML format.

Here’s what’s in src/main.rs: 

fn main() {
    println!("Hello, world!");
}
Cargo generated a “hello world” program for you, otherwise known as a binary crate. Let’s compile it but first change it to be the follwing:

fn main() {  //fn stands for function
    println!("HELLO COMP423");
}

Finally... Compiling and Running

We can now compile like so:

cargo build
   Compiling hello_world v0.1.0 (file:///path/to/package/hello_world)

The cargo build command compiles your Rust project and generates an executable kind of like the C language's gcc [filename.c] -o [output_filename] command that you may remember from COMP 211 which compiles the specified file and creates an executable object file to run the program.

How It Works

Compilation: cargo build compiles your project and places the resulting binary or library in the target/debug directory by default.

Default Build Mode: By default, cargo build compiles in debug mode. Debug builds prioritize faster compilation and include debug symbols, making them suitable for development and testing.

After building, the binary (executable) will be located in: 

target/debug/hello_world

You can finally run the executable manually to see the desired output: 

./target/debug/hello_world

You can also use the following command to compile and then run it, all in one step: 

cargo run

You should now see: 

HELLO COMP423

Success

Congratulations! You have built a development container in Rust!

Part 4: Pushing to GitHub

You can now run the following commands in order to push your amazing new Dev Container project to GitHub for the world to see!

git add . # this is for staging your changes
git commit -m "Successfully printed HELLO COMP423 with my own Rust Dev Container"
git push

Congrats you have now finished the tutorial and the whole world can see your amazing work on GitHub!

References

  1. Kris Jordan’s COMP 423 Tutorial
    Inspiration and structure for this tutorial.

  2. Rust Documentation: Creating a New Project
    Official guide to creating a new Rust project with Cargo.

  3. Rust: Learn Rust
    Rust's official learning resource.

  4. MkDocs Material Documentation
    Comprehensive guide to using MkDocs Material.

  5. Markdown Guide: Basic Syntax
    A beginner-friendly guide to Markdown syntax.