Dev-Containers for Programming C++

This describes how to easily run VS Code and a C++ compiler on your own computer with only a few setup steps. It lets you run everything locally without relying on any SFU servers. This is how I work in lecture, and it works under Windows, MacOS, and Linux.

A Dev Container is a nice way of packaging a bunch of development tools into one bundle. It uses a tool called Docker to run this bundle (a "container") without you having to worry about installing lots of software or configuring it.

Video demo of Dev Container for C++ .

Install Tools & Setup (once)

  1. Install Docker Desktop
    • Download Docker Desktop for your operating system (free!).
      If needed, use the drop-down on the Download button to select the correct version for your computer.
      On Windows, you likely have an AMD64 architecture unless you are using a MS Surface.
    • Run the installer.
    • Launch Docker Desktop. If it does not start up, see the troubleshooting below.
  2. Install VS Code on your computer:
  3. Install VS Code extensions:
    • On the left-hand side of VS Code, select Extensions.
    • Search for C/C++ Extension Pack, and install.
    • Search for Dev Containers, and install.
  4. On your computer, create a folder named cmpt130:
    • Suggest creating it in the usual place your operating system puts user files, such as under a Documents folder.
    • Ensure the folder (and the folders it is in) do not have any spaces in their names.
  5. In VS Code, open your cmpt130 folder:
    • Open VS Code
    • File > Open Folder, then select your cmpt130 folder.
  6. In VS Code, create the Dev Container description file:
    • On the left, click Explorer to bring up the Explorer view.
    • Click the New Folder button at the top of the Explorer view.
      Name the folder .devcontainer (the period at the front is needed).
    • Click on the .devcontainer folder and then click the New File button at the top of the Explorer View.
      Name the new file devcontainer.json
    • Open the file and copy-paste the following into it 
      {
    "name": "C++",
    "image": "mcr.microsoft.com/devcontainers/cpp:1-debian-12"
}
    • Save the file.

Launch VS Code with Dev Container (every time)

  1. Open VS Code.
  2. If needed use File > Open Folder to open the cmpt130 folder you created above.
  3. If needed, re-open the current folder as a Dev Container:
    • Click the green "><" button in the very bottom left of VS Code.
    • Select "Reopen in Container".
    • It will say "Connecting to Dev Container (show log)". This may take a few minutes to complete the first time you run it. It is trying to:
      • Launch Docker Desktop
      • Build the container for the C++ compiler
  4. When it finishes loading, you should see in the bottom left: ">< Dev Container: C++".
  5. Install the C/C++ Extension Pack
    • Click Extensions on the left, then search C/C++ Extension Pack; install.
      We install the C/C++ extension pack again because now it's inside the Dev Container.
  6. Write your C++ code (next)!

Writing your C++ Code with Dev Container

  1. If needed, in the Explorer view on the left, create a new folder for your activity (such as lab1 or asn2; don't put spaces in these names).
  2. Open (or create) a .cpp file in your folder (such as lab1/lab1.cpp or as2/calculator.cpp).
  3. Type in your C++ code into your file.
  4. In the top-right of the .cpp file, click the play button.
    • It should open a new terminal (or two) and show you the output of your program.
    • If asked to "Select a debug configuration", select the first one ("C/C++: g++...")
    • You should see the output of your program in the terminal!
  5. VS Code should now work with debugging the program as well.
    • With the Dev Container, your code is compiled inside the container, and is run inside of the container. So it's likely that the compiled program will not run on your computer outside of the container. This is not a problem! Your C++ code (in the .cpp file) is all we need!

Submitting Code from Dev Container

With Dev Containers, all your code is stored on your personal computer in the cmpt130 folder that you created to start with. Each time you launch VS Code you'll need to re-open that folder (if not done automatically), and possible "Reopen in Container".

To submit your C++ code (.cpp files) for labs or assignments, use your normal web browser and upload your files from the cmpt130 folder.

Note: Since the files are on your home computer, it's essential that you backup your files. I recommend having an automatic backup program for these files. Almost every student experiences a file loss some time throughout their degree (I did, twice!); have a backup!

Troubleshooting

  • General things to check:
    1. Ensure you have installed Docker Desktop.
    2. Try running Docker Desktop before "Reopen in Container".
    3. Double check the folder name (.devcontainer) and file name (devcontainer.json). Verify the contents of the file.
    4. Ensure your C++ file and folders are named without any spaces in the file name.
    5. Ensure your C++ file has a name ending in .cpp, such as lab1.cpp
    6. On Windows, ensure that WSL is working:
      Start Menu > type "Command"
      Run the command: wsl
    7. Ensure that Docker Desktop is correctly installed:
      Start Menu > type "Command"
      Run the command: docker run -it ubuntu /bin/sh
  • VS Code seems to freeze while displaying "Connecting to Dev Container (show log)"
    then click on the "show log" and see its progress. It may take a minute or two for this to complete the first time you run it.
  • This app cannot run on your PC... when installing VS Code or Docker Desktop:
    Ensure you are running the installer for your computer's architecture:
    • The architecture refers to the internal design of the CPU, such as AMD64 or ARM64. Note that Intel processors are often AMD64.
    • Windows
      • You know you have the wrong architecture if Windows displays "This app can't run on your PC; To find a version for your PC, check with the software publisher".
      • You can find the architecture of your computer here:
        Start Menu > type "cmd" > run: echo %PROCESSOR_ARCHITECTURE%
      • If it won't work after ensuring you have the correct AMD64 vs ARM64, then see how to turn on virtualization support mentioned below.
    • MacOS
      • "Apple silicon" processors such as M1, M2,... are ARM64. Intel Chips are sometimes referred to as X64.
      • You can find the architecture of your system by opening the Terminal application and running:
        uname -p
  • Missing WSL -- If Docker Desktop under Windows displays errors related to starting WSL (Windows Subsystem for Linux), you may need to install and configure WSL.
  • Docker Desktop does not start on Windows
    This can happen either when launching Docker Desktop directly (such as from its desktop icon), or when trying to launch the Dev Container in VS Code.
    • If Docker Desktop shows one of these errors:
      "Hardware assisted virtualization and data execution protection must be enabled in BIOS",
      or "importing WSL distro "WSL2 is not supported with your current machine configuration after mention of "deploying WSL2 distributions ensuring main distro is deployed: deploying "docker-desktop""
      or "This app cannot run on your PC" (this one can be related to AMD64 vs ARM64)
      then turn on virtualization for your computer (as described by Microsoft).
    • Otherwise, the problem is likely with WSL. Try the following:
      1. Ensure Windows has the "Virtual Machine Platform" feature enable:
        Start Menu > type "Turn windows features on or off"
        • Add a checkbox to "Virtual Machine Platform"
        • Add a checkbox to "Windows Subsystem for Linux"
      2. Open a command prompt: Start Menu > type "Command"
      3. Ensure WSL is installed:
        wsl --install
      4. Install a Linux distro for Docker Desktop to use: wsl --install -d ubuntu
        When asked for a user name, enter your first name (all lower case, no spaces).
        When asked for a password, type a simple memorable password (as you type, it won't show any characters).
      5. You may need to upgrade WSL:
        wsl --update
  • When creating a WSL distro, if you get the error "0x800701bc WSL 2 requires an update to its kernel component"
    Goto MS WSL support page and in Step 4, download the linux kernel update; look for "WSL2 Linux kernel update package for x64 machines".
  • When trying to reopen the folder as a container, if it shows an error "An error occurred setting up the container" then click "Edit devcontainer.json Locally". It will show you a log file which may give some hints to what went wrong.
    • If the log shows:
      dev container docker "Error response from daemon: Can't access specified distro mount service: stat /run/guest-services/distro-services/debian-bullseye.sock: no such file or directory"
      Try opening Docker Desktop, then go to Settings (top right) > Resources (left) > WSL Integration; add a checkmark to "Enable integration with my default WSL distro". Then try to "Reopen folder as container" through VS Code.
  • Error making directory with mkdir when launching Dev Container, or other problem with a specific WSL distro (see log)
    Delete all WSL distros and re-create a new one:
    1. Open a command prompt: Start Menu > type "command"
    2. List current WSL distros:
      wsl -l -v
    3. For each distro listed above, run the following (change "docker-desktop" to each other name too):
      wsl --unregister docker-desktop
    4. Create new distro:
      wsl --install -d ubuntu
      (See steps above for creating user and password).