Setting up a dev container for Rust

Primary author: Ezra Heinberg
Reviewer: Lixin Yang

Note

Certain steps in this tutorial will be quoted and/or paraphrased from the COMP 423 MkDocs tutorial page

Hello and welcome! This tutorial will teach you how to set up a basic Rust project in a development container. Just follow along with the steps, and enjoy the process!

Prerequisites

Before you start, be sure you have:

An account on GitHub: If not, sign up for one on GitHub.
Git installed: You can install it here.
VSCode installed: Download here.
Docker installed: Install it here.
A general familiarity with the command line: This will be helpful as you navigate this tutorial.

Part 1: Creating the Repository

Step 1. Create a Local Directory and Initialize Git

(1) Open your terminal or command prompt.

(2) Create a new directory for your project.

mkdir rust-tutorial
cd rust-tutorial

(3) Initialize a new Git repository:

git init

(4) Create a README file:

echo "# Basic Program in Rust" > README.md
git add README.md
git commit -m "Initial commit with README"

Step 2. Create a Remote Repository on GitHub

(1) Log in to your GitHub account and go to the Create a New Repository page.

(2) Fill in these details:

Repository Name: rust-tutorial
Description: "A short program written in Rust!"
Visibility: Public

(3) Do not worry about a README, .gitignore, or license for now.

(4) Click Create Repository.

Step 3. Link your Local Repository to GitHub

(1) Add the GitHub repository as a remote:

git remote add origin https://github.com/<your-username>/rust-tutorial.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.

(3) Push your local commits to the GitHub repo:

git push --set-upstream origin main

Info

What is --set-upstream?

git push --set-upstream origin main pushes the main branch to the remote repository origin. The --set-upstream flag sets up the main branch to track the remote branch, meaning future pushes and pulls can be done without specifying the branch name and just writing git push origin when working on your local main branch. The corresponding short flag is -u.

(4) In your web browser, refresh your GitHub repository to see that the same commit you made locally has now been pushed to remote. You can 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 a Dev Container

A development container is useful to ensure that your development environment is consistent across different machines. Follow the steps below to configure and create one.

Step 1: Add Dev Container Configuration

(1) Open the rust-tutorial folder in VSCode via File > Open Folder.

(2) Press Ctrl-Shift-P (Cmd-Shift-P on Mac) and search for Dev Containers: Add Dev Container Configuration Files.

(3) Select Add configuration to workspace.

(4) Search for and click Rust.

(5) Select bullseye.

(6) Click OK (top right corner) until your .json file is created.

(4) A devcontainer.json file is now added to your folder.

Step 2: Customizing Dev Container for Your Project

When you create the .json file, it should look like this:

// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/rust
{
    "name": "Rust",
    // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
    "image": "mcr.microsoft.com/devcontainers/rust:1-1-bullseye",

    // Use 'mounts' to make the cargo cache persistent in a Docker Volume.
    // "mounts": [
    //  {
    //      "source": "devcontainer-cargo-cache-${devcontainerId}",
    //      "target": "/usr/local/cargo",
    //      "type": "volume"
    //  }
    // ]

    // Features to add to the dev container. More info: https://containers.dev/features.
    // "features": {},

    // Use 'forwardPorts' to make a list of ports inside the container available locally.
    // "forwardPorts": [],

    // Use 'postCreateCommand' to run commands after the container is created.
    // "postCreateCommand": "rustc --version",

    // Configure tool-specific properties.
    // "customizations": {},

    // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
    // "remoteUser": "root"
}

We are going to add some things to the file.

(1) Uncomment out the customizations section and edit it to look like this:

"customizations": {
    "vscode": {
        "extensions": [
            "rust-lang.rust-analyzer"
        ]
    }
}

(Make sure you add a comma on the "image" line of the file!)

(2) Uncomment out the line that says "postCreateCommand": "rustc --version",

(3) Now, press Ctrl-Shift-P (Cmd-Shift-P on Mac), search for Dev Containers: Reopen In Container and click on it.

Part 3: Your first Rust program

Congratulations on making it this far! You will now create your first program in Rust.

Step 1: Create a `main.rs` file

(1) Open a new terminal in VSCode and run this command:

cargo new rs-tutorial --bin --vcs none

Info

What does this mean?

The command cargo new rs-tutorial --bin --vcs none creates a new Rust project using the Cargo package manager. rs-tutorial is the name of the directory your main.rs file will be placed in. The --bin flag specifies that the project being created is a binary crate, which means it will compile into an executable program. The --vcs none flag disables version control system (VCS) initialization.

(2) Navigate to the main.rs file (rs-tutorial folder > src folder > main.rs).

You will notice the file already has some prewritten code in it. This is a simple function that prints "Hello, World!" to standard output.

(3) Simply change the text within the println!(); function to "Hello COMP423", save the file, and you're done with this part!

Step 2: Compiling and running the program

Now that your program is ready to be run, we will look at two different ways of accomplishing that. To start, run cd rs-tutorial.

(1) The `cargo build` command

The cargo build command compiles your project but does not run the executable that results.

This is useful if you want to check that your code compiles correctly without executing it.

This is equivalent to running gcc to compile a program and stopping after the a.out executable is created.

To try it out, run cargo build in your terminal in VSCode.

You will see output that looks like this:

Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.01s

To run it, type this command: ./target/debug/rs-tutorial.

(2) The `cargo run` command

The cargo run command compiles and builds your Rust program in one step.

This is equivalent to running gcc to compile a program and subsequently running ./a.out.

To try it out, run cargo run in your terminal in VSCode.

Part 4: Pushing Your Work to GitHub

If you wish to push your work to GitHub, run these commands in the terminal:

git add .
git commit -m "Hello COMP423 in Rust"
git push -u origin main

Congratulations on finishing this tutorial! You should now have a familiarity with some important coding concepts.