1.1 Installation

Install the following tools:

• VS Code
• Docker Desktop
• Python

1.2 Setup

1. Download cs340.zip which contains some basic VS Code and Docker setup and unzip it in a place that you can easily access (you’ll need to upload from and download to this folder). We’ll call the folder this creates your cs340 folder for the entire semester.

   What the zip file contains

   There is a file named Dockerfile (that exact capitalization, no file extension) with the following text inside of it:

   FROM gcc
   RUN DEBIAN_FRONTEND=noninteractive \
       apt-get update && \
       apt-get install --yes --no-install-recommends \
           make \
           clang lld gdb lldb valgrind \
           curl wget git \
           less nano jq xxd \
           python3-pytest-aiohttp python3-pip python3-requests python3-dotenv \
           man manpages manpages-dev \
       && rm -rf /var/lib/apt/lists/*
   ENTRYPOINT bash

   Docker is a tool for creating an isolated environment called a container on your computer. We use it get the power of a modern Linux development environment on non-Linux computers.

   Dockerfile is the default name used for files that describe how to create a container image. In this Dockerfile, we do the following:

   1. Start from a full Linux installation with the Gnu Compiler Collection pre-installed.
   2. Disable user interaction while installing additional packages:
      • make, a build configuration tool.
      • several C programming tools: the clang compiler, lld linker, gdb and lldb debuggers, and valgrind memory checker.
      • several web tools: curl is a low-level web access tool, wget is a more user-friendly alternative, and git is specifically for the most popular version control systems.
      • several command-line convenience tools: less for viewing long text, nano for editing text, jq for parsing JSON, xxd for showing binary files as hexadecimal.
      • Python with a few third-party packages pre-installed.
      • Manual pages, the official documentation for most things C and Linux.
      After the installation we delete the installation metadata to save space.
   3. Pick a starting terminal, the Bourne Again Shell.

   The first time we use this file docker will download all these programs from dockerhub and build them into an image, which is a template or program for creating containers. Each time we connect to this using VS Code, the image will be used to create a fresh container in which we can run all of these programs. That way if we somehow mess up our container (for example by deleting a program we need), we can simply restart VS Code and a fresh container will be created from the image.

   In addition to the Dockerfile we also provide a file .devcontainer/devcontainer.json telling VS Code how to run the Docker image the Dockerfile creates. It’s mostly a default devcontainer.json file, but has three tweaks: it increases the default limit on open file descriptors (which valgrind uses many of), lists VS Code extensions to include when running the docker image, and has a place to list ports you want to open in the image (which we’ll start using about half-way through the semester).

2. Run Docker Desktop – it will do some first-time setup to finish installing itself.

3. Run VS Code

   1. Either open a terminal, cd into your cs340 folder, and type code . (preferred) or open VS Code in another way and them use Open Folder from the File menu and open your cs340 folder (less preferred).

   2. Click the Extensions icon in the left bar. Inside this, install the following extensions, all from Microsoft:

      • Dev Containers
      • Remote - SSH
      • C/C++
      • Python (which should automatically also install Python Debugger)

   3. Click the remote icon in the bottom-left corner of VS Code

      1. Select Reopen in Container.

         If you are asked where to add a configuration…

         If Reopen in Container asks you where to add configuration, that means VS Code and Docker aren’t talking to one another properly. Close VS Code, uninstall and re-install Docker, then re-open VS Code and try again. If that doesn’t fix it, let us know on Campuswire or tutoring hours and we’ll look for another solution.

         If you get an error message…

         Try opening a terminal and running docker login (see campuswire #12)

         Try clearing your docker cache (or uninstalling and reinstalling docker) (see campuswire #22)

      2. Wait for the container to build.

         If you get an error message…

         Talk to a member of course staff; they can often resolve this.

         If not, there is an alternative path, though it will require some small setup effort for each MP:

         1. Build a Docker image manually: from a terminal in the directory containing Dockerfile, run

            docker build -t cs340_image .

            If it has errors, post them on CampusWire and we’ll suggest changes to the Dockerfile to fix them.

         2. In the .devcontainer/devcontainer.json of every MP, replace "build: {…}, with "image": "cs340_image",

1.3 Verify

When running VS Code, you should see the bottom-left blue button says Dev Container: Existing Dockerfile. If it does not say this, redo the Reopen in Container step from Setup.

In a terminal in VS Code (e.g. by pressing Ctrl+`), you should

• See the prompt line is root@…:/workspaces/cs340# where the first elided bit is a long hexadecimal number and the second is the name of the directory containing the Dockerfile.¹¹ If you opened the log when the Dockerfile was building, the terminal might be in a strange log-display state that has no prompt and doesn’t let you type anything. The most reliable fix for this that we’ve found is to restart VS Code.
• Run gcc --version to see a version number (gcc (GCC) 14.2.0 or later).
• Run valgrind --version to see a version string (valgrind-3.19.0 or later).
• Run pydoc3 aiohttp to get a screen that says Help on package aiohttp (press Q to exit this screen).

1.4 Working on MPs

Each MP will have a zip file for you to start with. These will have some VS Code configuration in a subdirectory .vscode as well as some starter code. Unzip these inside the cs340 directory, and then open the MP directory in VS Code (cd into their directory and type code . to start CS Code, or from an open VS Code use File → Open Folder)

For example, for MP0 you’d have the following file structure on your hard drive

cs340/
├── .devcontainer/
│   └── devcontainer.json
└── mp0/
    ├── .devcontainer/
    │   └── devcontainer.json
    ├── .vscode/
    │   ├── launch.json
    │   └── tasks.json
    ├── tests/
    │   ├── lib/
    │   │   └── catch.hpp
    │   ├── tay-small.gif
    │   ├── tay-small-illinify-expected.gif
    │   ├── test-all.cpp
    │   └── test.cpp
    ├── gif.c
    ├── gif.h
    ├── main.c
    ├── Makefile
    ├── tay.gif
    └── tester.sh

and in VS Code’s Explorer pane you’d see something like this:

  EXPLORER

⌄ MP0 [DEV CONTAINER: EXISTING DOCKERFILE]
  › .devcontainer
  › .vscode
  › tests
  C gif.c
  C gif.h
  C main.c
  M Makefile
  🖻 tay.gif
  $ tester.sh

If you don’t see the dev container:existing dockerfile part then click the remote icon in the bottom-left corner of VS Code and select Reopen in Container. If that doesn’t work, make sure the folder structure is correct, with cs340/ containing both Dockerfile and mp0/ (or whatever MP you are working on).

2.1 Identify and Turn On your VM

You will be given a single VM.²² It’s name will have the form fa24-cs340-num.cs.illinois.edu where num is a 3-digit number unique to you this semester. You can find the exact name at https://csid-basic-apps.cs.illinois.edu. If you have been enrolled in the course for at least two schooldays and no VM is listed there for you, contact your professor.

The VM will be turned off after a few hours of idleness. To turn it back on, follow these directions: https://answers.uillinois.edu/illinois.engineering/page.php?id=108475. Your VM needs to be on to interact with it in any way.

Your VM’s password is your NetID password. If you change your NetID password it may take a couple of days for the VM to catch up.

2.2 Setup VS Code VM integration

1. If you have not already done so, follow all of the Installation and Setup steps and open VS Code.
2. Click the remote icon in the bottom-left corner of VS Code

   1. Select Connect to Host…

   2. Select Add New SSH Host…

   3. Type ssh netid@fa24-cs340-num.cs.illinois.edu, filling in your NetID and VM number.

   4. Pick a config file from the available options; the first displayed option should work fine.

   5. In the new VS Code window that opens up, open up a terminal. It should have your VM name on the prompt line.

   6. In the VS Code terminal, install needed software:

      sudo apt-get update
      sudo apt-get install gcc build-essential gdb valgrind git curl wget python3-pip
      python3 -m pip install aiohttp requests pytest python-dotenv

2.3 File transfer

Your virtual machine has a separate disk from your personal computer. To move files back and forth, use scp.

1. In a VS Code terminal running the virtual machine,
   1. cd into the directory where the files are or where you want them to be
   2. pwd to see the full directory path; for example, /home/netid/cs340/mp18
2. In a VS Code terminal running the docker container,
   1. cd into the directory where the files are or where you want them to be
   2. use scp currentLocation desiredLocation, where
      • One of the locations has the form netid@fa24-cs340-num.cs.illinois.edu:/home/netid/cs340/mp18
      • The other location is a local filename
      • The desiredLocation may be a directory, meaning keep the same filename. If so, the currentLocation can be a wildcard like * or repeated to transfer several files at once.

For files located online, you can download them to the VM directly by using wget https://example.com/file/to/download.zip