Development Environment Guide

This guide is based on the cs300 lab for setting up your development environment.

Introduction

Docker is a convenient way to manage virtual environments as “containers.” We will be using it to run Ubuntu 22.04 (jammy), a Linux-based operating system. If you’ve taken CS 300, the container setup will be very similar with a few extra tools preinstalled.

Why are we using this?

With virtualization, we can specify a standard development environment on any machine, so your code will work no matter where it’s run. (You won’t need to log into the CIT department machines to write, test, or hand in your code!)

Installing Docker and X Server

Your computer is probably running Mac OS, Windows, or Linux. These different operating systems all come with different libraries and preinstalled software. A Virtual Machine can establish the same software environment for everyone.

Note: Software inside a VM believes it is running on a physical computer, even though it is running within an OS within another computer. Achieving this level of virtualization has costs, including the cost of emulating the underlying hardware.

In this class, we will use a container, a technology that emulates an OS without the full overhead of a VM. The container runs a Linux-based operating system, Ubuntu. The autograder also runs a Linux-based OS, so if your code works in the container, it will work on the autograder.

Docker

Docker is one of the most popular container solutions and widely used in industry. In CS 1952Y, we use Docker because it lets you run a course container on Windows, Mac OS, or Linux.

You may download Docker here. On Linux machines, follow the instructions here.

After downloading Docker, follow Docker’s instructions to install it on your OS. Accept if Docker asks for privileged access.

On Windows or Mac OS, open the Docker Desktop application after it has been installed. You may see a message similar to “Docker Desktop is Starting…”. Once this message goes away, your Docker has started successfully!

Verify Docker is installed by executing the following command in a terminal:

$ docker --version

A Docker version number should be printed.

After installing Docker, a Docker process (the Docker daemon) will run in the background. Run the following command to verify:

$ docker info

This should print some information about your Docker installation.

If you see the following error:

ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

it means Docker hasn’t started running yet. On Windows or Mac OS, ensure your Docker Desktop is running. On Linux, try the command sudo systemctl docker restart in a terminal.

Once Docker Desktop is running, modify the default docker resource settings. Open up Docker Desktop and click on the setting symbol in the top right. Go to the ‘Resources’ tab and set the CPU limit to at least 8, the memory limit to at least 8 GB, the swap to the maximum available, and the virtual disk limit to at least 64 GB.

You can follow additional instructions from the cs300 lab if you are on Windows and do not have WSL (Windows Subsytem for Linux) set up yet. Make sure to run the docker commands below (in “Setting up the dev environment”) from WSL, instead of from PS/cmd/git bash

X Server

X11, or X Window Subsystem is a framework that powers most GUI applications in Linux. Ripes requires a GUI interface, so in order to run it within a Docker container, we need to connect to a program on the host (the X server) that can draw its window.

Instructions for Mac OS

Download and install XQuartz here. Run the installer and allow the app to make changes to your computer when prompted. During installation, you may be asked to log out and log back into your computer in order to update your system environment.

Once XQuartz is installed, open it from the applications menu. After it opens, navigate to the menu bar at the top of your screen and select XQuartz > Preferences. Go to the Security tab and check the box labeled "Allow connections from network clients". This will allow the container to connect to your X server.

Quit XQuartz by selecting XQuartz > Quit from the menu bar. XQuartz should reopen automatically when you start the container later.

Instructions for Windows

Download and install VcXsrv here. Run the installer (the default options should be fine), and allow the app to make changes to your computer when prompted.

After installing VcXsrv, run it from the start menu. If presented with any questions, accept the defaults. Once VcXsrv has finished starting, you should see it running in your system tray (bottom right corner of the screen).

NOTE: Each time you restart your computer, you will need to start VcXsrv whenever you need to run the container.

Instructions for Linux

Linux most likely has an X server already installed so you shouldn't have to do much here! Check if you have xhost by running which xhost.

If xhost is not found, you will need to install it on your system. On Ubuntu or Debian, you can do this by running sudo apt-get install x11-xserver-utils. On other distributions, you will need to install a similar package (the name may be different though).

Once you have installed xhost, which xhost should print something similar to /usr/bin/xhost.

Setting Up the Dev Environment

In Docker, an environment is defined as a Docker image. An image specifies the operating system environment that a container provides. An image can also contain additional software dependencies and configurations. These instructions are specified in a file, the so-called Dockerfile.

You will now download the course’s setup code and create the CS 1952Y Docker image!

 Mac OS only: Install Apple development tools

If you're running on Mac OS, you will need to install a set of Apple-recommended command-line tools via the following command:


    xcode-select --install

This ensures that your computer has installed git, a program we'll use later. Alternatively, you may also download and install git directly, following instructions from here.

Do the following to set up your development environment.

Enter the directory on your computer where you want to do your coursework. For Windows users, choosing somewhere in the C drive will make the following steps easier.

Then, enter the following command to download our development environment to the new subdirectory DEV-ENVIRONMENT (you can choose your own name, DEV-ENVIRONMENT is a placeholder!):
```
 $ git clone https://github.com/browncs1952y/cs1952y-s24-devenv.git DEV-ENVIRONMENT
```
This command clones a Github repository onto your computer.
Run cd DEV-ENVIRONMENT to enter the directory you have just created
Inside this folder, do the following:
```
$ ./docker/cs1952y-setup-docker
```
This will attempt to pull our Docker image that has been prebuilt. If you wish to do so, ./docker/cs1952y-build-docker will build the image from scratch (this can take up to 20 minutes).

The setup script should tag the image correctly, but if it doesn’t (you get an error saying the image was not found), you can also tag it manually:
```
 $ arch=$([ $(arch) = arm64 ] && echo "arm64" || echo "latest") && docker tag mramesh5/cs1952y:$arch cs1952y:$arch
```
After this, you can run Docker for the first time:
```
$ ./cs1952y-run-docker
```
You can now interact with the shell of the container. You can use Ctrl-D to exit

Prior to restarting the docker container via ./cs1952y-run-docker --clean, you may need to copy the gem5 and Ripes directories to a temporary location (see Pulling Updates to the Container for more information).

Confirming that the Dev Environment Works

To confirm that the dev environment is set up correctly, you can check whether the Ripes GUI is working. To do this, run the container using ./cs1952y-run-docker. Then, navigate to the Ripes directory – cd Ripes. Run

make -j8. This shouldn’t take long because the Docker image comes with Ripes precompiled.
./Ripes. A GUI screen titled Ripes pop up.

Pulling Updates to the Container

Do the following to pull updates to the container (note that this will solely update your local Docker image, not the Dockerfile itself):

To update the container, rerun the setup script
```
$ ./docker/cs1952y-setup-docker
```
If you have made changes to the gem5 or Ripes directories, copy your existing gem5 and Ripes directories from DEV-ENVIRONMENT/home/ to a different location temporarily. These may get overwritten when you restart the Docker container. You can use
```
 cp -R DEV-ENVIRONMENT/home/gem5 DEV-ENVIRONMENT
 cp -R DEV-ENVIRONMENT/home/Ripes DEV-ENVIRONMENT
```
Remove the existing cs1952y container and restart it:
```
$ ./cs1952y-run-docker --clean
```

If you also want to pull all updates to the Dockerfiles within the dev environment, you can run git pull.

Shared Folders

“If my docker container is a separate (virtual) computer than my laptop, how will I move files between the two?”, you may ask. Great question! You’ll move files between the two in any of the ways you can move files between any two computers! (Bear with us!)

To get files to and from department machines, you may have used things like scp, sftp, and Cyberduck, which allow you to copy files over the network. These work, but are inconvenient if you’re constantly moving them back and forth.

If you’re lucky, you may have been exposed to FUSE and sshfs, which allow you to mount a filesystem over the network. This allows your computer to navigate the remote files as if they were stored locally, which means any changes you make are happening on both ends automatically.

Inside of the container, your home directory (/home/cs1952y-user, or ~) is actually a mount of the home directory inside your DEV-ENVIRONMENT directory. Any changes you make in one will be visible in the other.

If you move or rename your dev-environment folder

Your Docker container will still try to mount to the original dev-environment path, even after you rename, remove, or move the folder DEV-ENVIRONMENT.

After moving your dev-environment folder, you’ll need to delete the old container and start a new container. You can do so with ./cs300-run-docker --clean. You should be able to enter a container, and see all of your work now!

If you have filesystem sync issues on Mac OS

This might be caused by gRPC FUSE, which is sometimes buggy on MacOS. Go into your docker settings and make sure that the gRPC FUSE checkbox is not checked, or that the sync method is set to VirtioFS.

Text Editors and IDEs

What development environment or editor to use is a question that divides people and has led to countless hours being wasted on heated discussion, offline and online for decades. Some people prefer very simple editors that run in their terminal, while others prefer graphical integrated development environments (IDEs). For CS 1952Y, we don’t really care what you use – if it works for you, great!

To make your life easier, however, you probably want to use an editor with syntax highlighting for C++, the main programming language we’ll use in CS 1952Y.

You can edit your source code inside the course container, or on your normal operating system. Recall that the home directory inside the container is a mount of your local cs1952y/home directory (or whatever you named it). This means that you can install any editor or IDE of your choice on your local machine, edit your files and work on your assignments locally, and all of your changes will be reflected in your container! You can then compile, build, and run your assignments inside your container. This is the power of mounting :fire:!

There are plenty of great choices for text editors. If you’re not sure which one to install, we recommend VSCode. It has very nice integration with our Docker container, and it’s nicely customizable with extensions.

How to link VSCode with the course Dev Environment

Download and install VSCode on your computer (not the course container) normally
Navigate to the extensions tab by clicking this icon on the left side of the screen:
Search for and install the "Docker", "Dev Containers", and "WSL" VSCode extensions via the extensions tab
Make sure your course container is running (either by connecting to it, or checking the docker desktop app)
Click the green button in the bottom left of VSCode, then click "Attach to running container" and select your CS1952Y course container
You can now open any folder you want to edit, and can get a terminal from your course container by clicking View > Terminal

Installing programs on Linux (in your course container)

Our containers come with a few programs pre-installed, but what if we want more? With a text-based interface like the command line, it’s quite difficult to navigate the web and find a suitable download link. Instead, we use a program called a package manager which can automatically download, install, and update programs. We’ll be using a manager called apt. apt can install many things, including tools to build (or compile), and debug your code. Our containers already come with these tools for your convenience.

As an example, to install fortune, you would run

$ sudo apt update
$ sudo apt install fortune