Dev Containers: Quick Start

A Dev Container gives you a pre-configured programming environment inside VS Code. Instead of installing the RISC-V compiler and other tools directly on your laptop, VS Code runs them inside a container.

This helps make sure everyone in the class is using the same setup.

What you need

Install these on your computer:

1. Docker Desktop
2. Visual Studio Code
3. The VS Code extension Dev Containers

You only need to install these once.

Note for those installing Docker on Mac! If you have the issue where VSCode is not recognizing your Docker installation, please open Docker Desktop –> Settings –> Advanced, change the CLI tools configuration from User to System.

Opening the COMP 311 environment

Download or clone the assignment/starter folder, then open that folder in VS Code.

You should see a folder named:

.devcontainer

inside the project.

Open the VS Code Command Palette:

Mac:     Cmd + Shift + P
Windows: Ctrl + Shift + P

Search for:

Dev Containers: Reopen in Container

and select it.

The first time you do this, VS Code may take a few minutes to build the environment.

How do I know I am inside the container?

After the container opens, start a new terminal in VS Code.

You should see a prompt that looks something like:

vscode@...

rather than your normal laptop username.

Then run:

311-check

You should eventually see:

Success: generated RV32I assembly.

If you see that, your environment is ready.

Important: host computer vs. container

The RISC-V tools are installed inside the Dev Container, not directly on your laptop.

So this may fail in your normal Terminal app:

311-check

with an error like:

riscv64-unknown-elf-gcc: command not found

That usually means you are running the command outside the container.

Open the project in VS Code and use:

Dev Containers: Reopen in Container

before running the COMP 311 commands.

Compiling C to RISC-V

To compile a C program without compiler optimizations:

311-compile -O0 examples/scale.c

To compile the same program with optimization:

311-compile -O2 examples/scale.c

Generated files will appear in the build/ directory.

For example:

build/scale_O0.s
build/scale_O0.o
build/scale_O0.dump

The most useful file for this assignment is usually:

.s

which contains the compiler-generated RISC-V assembly.

You can open it directly in VS Code.

Assembling hand-written RISC-V

If you write your own assembly file:

myprogram.s

you can assemble it using:

311-assemble myprogram.s

The resulting object code and disassembly will appear in build/.

Useful commands

311-check

Checks that the environment is working.

311-compile -O0 file.c

Compile C to RV32I with no optimization.

311-compile -O2 file.c

Compile C to RV32I with compiler optimization.

311-assemble file.s

Assemble hand-written RV32I assembly.

ls build

See your generated files.

cat build/example_O0.s

Print generated assembly in the terminal.

If something goes wrong

If the container does not open correctly, try:

Cmd/Ctrl + Shift + P

then:

Dev Containers: Rebuild Container

If you get:

command not found

for a COMP 311 or RISC-V command, first check that you are actually inside the Dev Container.

You can also run:

whoami

Inside the container, this will typically print:

vscode

Mental model

You can think of the setup like this:

Your laptop
    |
    +-- VS Code
          |
          +-- Dev Container
                 |
                 +-- RISC-V compiler
                 +-- assembler
                 +-- course scripts
                 +-- your project files

Your files are still visible on your computer, but the programming tools run inside the container.

The main rule to remember is:

Open the project in the Dev Container before running COMP 311 commands.