« Back to the main CS 300 website

Lab 0: Getting Set Up (Docker & Git)

Due February 1, 2022, at 8:00pm EST

Introduction

Welcome to your first lab! The main focus will be to get you set up with the tools we’ll be using throughout CS300, and give you an intuitive understanding of each one.

The main tools we’ll be using are Docker, a convenient way to manage virtual environments as “containers”, and Git, the most prominent version control software.

Why are we using these tools?

• You’ll be able to develop locally. 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!)
• Version control is awesome. All changes to your code are tracked and can be reverted, making testing and debugging significantly more bearable. Your changes are also semi-automatically merged with other people’s, making collaboration easy. CS 300 has no partner assignments, but version control will be useful for other courses that do.
• It’s how it’s done in the industry. Most companies use some form of version-control in order to better manage projects and collaboration, and use machine virtualization for easier deployment and testing.

Development Environment Setup

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

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. Our grading server also runs a Linux-based OS, so if your code works in the container, it will work on the grading server.

Docker

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

$ docker --version

$ docker info

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

Windows-based computers only

To run the following steps in this lab, you will need to set up Windows Subsystem for Linux (WSL). WSL should already be enabled after you install Docker, but you may still need to install a Linux distribution. This will run in an actual Linux VM, and you will run your Docker container within that VM (turtles all the way down for you!).

1. Do I have a Linux distribution (Linux distro) installed?
   • Run wsl -l -v in the Command Prompt or Powershell. If there is only “Docker Desktop” and “Docker Desktop Data”, you do not have a Linux distribution installed. Proceed to step 2.
   • Otherwise, you have a Linux distro installed. Proceed to step 3.
2. Install a Linux Distribution.
   • Run wsl --set-default-version 2 to ensure Ubuntu will be installed under WSL 2.
   • Install “Ubuntu 20.04” from Microsoft Store.
   • Click “Open” after Ubuntu is downloaded. A terminal will open and guide you through the installation process.
3. Ensure your Linux Distribution runs on WSL 2.
   • From the output of wsl -l -v, find out if your Linux distro is using WSL 1 or WSL 2. If it’s WSL1:
     • Run wsl --set-version <distro name> 2 to update your distro to use WSL 2.
4. Set your default Linux distro
   • Run wsl --setdefault <distro-name> to configure your default Linux distro. <distro-name> should be “Ubuntu-20.04” if you installed using step 2.

Enter wsl in your Command Prompt or Powershell, and you’ll enter into your WSL! For the rest of the Lab, run commands within your WSL Linux environment, unless otherwise specified.

You will also need to connect Docker with WSL. To do so, open your Docker Desktop’s settings (on its top right corner), click “Resources”, “WSL integration”, then enable integration with your Linux distro. Then, click “Apply and Restart”.

Set up CS 300 Docker 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.

Next, you will download the the course’s setup code and create the CS 300 Docker image!

macOS only: install Apple development tools

If you’re running on macOS, 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 below. Alternatively, you may also download and install git directly, following instructions here.

$ git clone https://github.com/csci0300/cs300-s22-devenv.git DEV-ENVIRONMENT

$ cd docker             # enters the folder containing Dockerfiles
$ ./cs300-build-docker  # builds a docker image you'll use in the semester

Entering the container

Once you created your Docker image, you will want to create a container running this image.

$ ./cs300-run-docker          # enters your Docker container
cs300-user@9899143429a2:~$    # you're inside the container!
cs300-user@9899143429a2:~$ uname
Linux
cs300-user@9899143429a2:~$ echo "Hello world!"
Hello world!
cs300-user@9899143429a2:~$ ls -lah
total 24K
drwxr-xr-x 6 cs300-user cs300-user  192 Jan 25 22:23 .
drwxr-xr-x 1 root       root       4.0K Jan 25 22:25 ..
-rw-r--r-- 1 cs300-user cs300-user  132 Jan 25 22:23 .bash_profile
-rw-r--r-- 1 cs300-user cs300-user 4.0K Jan 25 22:23 .bashrc
-rw-r--r-- 1 cs300-user cs300-user   25 Jan 25 22:23 .gdbinit
-rw-r--r-- 1 cs300-user cs300-user  813 Jan 25 22:23 .profile
cs300-user@9899143429a2:~$ exit  # or Ctrl-D

Instructions for Windows only

If you see errors along the lines of bash: '\r': command not found or bash: /home/cs300-user/.bash_profile: line 5: syntax error: unexpected end of file when you enter the container, you need to convert your files’ line endings (characters that delineate the end of a line) from Windows to UNIX (Linux) format.

To do so, do the following:

1. Enter into WSL. You may do so by opening Ubuntu in the start menu or through the wsl command.
2. Use cd to navigate to the folder where you just cloned the setup repository. If you cloned your setup repository to your C: drive, use cd /mnt/c to enter the C: drive from your WSL.
3. Run sudo apt-get update, then install dos2unix with sudo apt-get -y install dos2unix.
4. Run dos2unix ./cs300-run-docker (you should only need to run this once).
5. Next, run ./cs300-run-docker.
6. If you see the next line begins with cs300-user@@9899143429a2:~$ ..., you’re inside the container, hopefully without errors!

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. (Git would technically also fall under this category, even though it’s fancier, as you’ll find out shortly.)

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/cs300-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.

$ touch cool_file
$ mkdir awesome_folder
$ cd ..
$ ./cs300-run-docker

cs300-user@9899143429a2:~$ ls # print the file and dir we just created
awesome_folder    cool_file

cs300-user@9899143429a2:~$ rm cool_file
cs300-user@9899143429a2:~$ cd awesome_folder
cs300-user@9899143429a2:~$ touch even_cooler_file
cs300-user@9899143429a2:~$ exit # or just CTRL-D

$ cd home            # this enters the mounted directory
$ ls                 # should just show awesome_folder
awesome_folder
$ cd awesome_folder
$ ls                 # should show even_cooler_file
even_cooler_file

./cs300-run-docker --clean

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 300, 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 and C++, the main programming languages we’ll use in CS 300.

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 cs300/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 !

Below are some popular choices for C and C++ development:

Simple editors:

• vim is a classic, highly configurable editor that comes with many Linux distributions. It’s a multi-mode editor, meaning that you have to switch between modes (e.g., input, select, edit). It runs in the terminal, all functions are controlled by keystrokes and internal commands, and vim can be customized with plugins.
• emacs is the main competitor to vim. It is not multi-mode, but also runs in the terminal. It allows scripting and plugins in Lisp, and its default keybindings are based heavily around the Ctrl key.
• Sublime Text is a modern, lightweight, cross-platform editor highly customizable via plugins and with a strong fulltext search.

IDEs:

• CLion is a cross-platform IDE built by JetBrains specifically for C and C++ development. It helps you with code navigation, generation, and refactoring. Students qualify for free licenses. Runs on macOS, Linux, and Windows.
  • CLion works with CMake (an open-source system for managing the build process, comparable to make) to analyze and understand project context.
  • If you choose this option, you should import your project into CLion, so that it automatically generates necessary CMake files for you. Please look this up for more details.
• VSCode is a free IDE built by Microsoft, and has support for all major languages (including C and C++). It also comes with built-in Git integration. Runs on macOS, Linux, and Windows.
• XCode is Apple’s official free IDE for Mac and iOS app development, and supports C and C++ (in addition to various other languages). Runs on macOS.

Installing text editors

Our containers do not include terminal-based text editors like vim and emacs. To make it easier to edit code within the container, let’s install some text editors!

Linux distributions, like Ubuntu, let you manage your packages, or tools, with a neat tool called apt. This tool handles installing, deleting, and updating packages.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.

Here, we’ll use apt to install some text editors!

$ sudo apt-get update

$ sudo apt install <package>

$ sudo apt install vim
$ sudo apt install emacs-nox

Git

Git is an awesome version control tool for your code. In essence, it allows you to continuously save your project as a sequence of small changes instead of one final thing. Some of the cool things this grants you are:

• Reverting changes in case your code breaks.
• Merging changes with partners, even if you’re working on the same file.
• Having multiple branches, to test out implementations without ruining your code.
• Retrieving stencil code and handing in solutions, like you’ll be doing throughout the semester!

Learning Git

There are a ton of resources out there to learn about Git, so we won’t try to recreate them. Instead, we’ll link you to a few tutorials, and encourage you to find more on your own!

Before you start running Git commands, you’ll need to configure your name and email in Git.

cs300-user@9899143429a2:~$ git config --global user.name "Jennifer Stevenson"
cs300-user@9899143429a2:~$ git config --global user.email "jennifer_stevenson@brown.edu"

cs300-user@9899143429a2:~$ git config --global credential.helper store

Now, take a look at some beginning Git tutorials.

GitHub Classroom Setup

We use GitHub Classroom to distribute the assignments throughout the semester. You will be working with two repositories: one for projects, and one for labs. Each will contain a directory for each project or lab.

$ ./cs300-run-docker
cs300-user@9899143429a2:~$    # inside the container!

$ git clone git@github.com:cs300-s22-projects-YOURUSERNAME.git
$ git clone git@github.com:cs300-s22-labs-YOURUSERNAME.git

Once you cloned the repository, you should see the snake in the projects repo, and the lab0 directory in the labs repo. These are the only assignments we’ve released so far; you will add others later.

Exercise

At this point, you have your version control set up. Let’s do a quick exercise to practice your newfound Git skills. The results of this part of the lab are what you hand in at the end.

Inside the lab0 you should see a file hello_world.c. This is a Hello World program, and is the one you’ll make changes to. To run the program you need to compile it first (we will cover compilation in detail in a later lab). For now, just use the following commands:

$ gcc hello_world.c -o hello_world # to compile it
$ ./hello_world # to run it

Note: Make sure you do everything inside of your container.

$ git add hello_world.c
$ git commit -m "Added tounge twister."
$ git push

You have now committed your changes to Git and they are stored in the version history (git log should show your new commit!). You’ve also pushed the new commit to GitHub’s servers. Next, you’ll set up the grading server and hand in this lab.

Handin Instructions

Head over to the grading server. If you were registered for CS 300 on the first day of classes, you should have received credentials by email.

Step 1: Log into the grading server with the password you received. Once you’re logged in, enter your GitHub username (at the top).

Step 2: Add the repository URL under the “Labs” category. Click “Labs” to initiate a fetch of your repository from GitHub.

Note: If your GitHub account is not linked to your Brown email address, the grading server will give you a command to run to verify your repository.

Step 3: You should see your commit listed on the Labs page, as shown above. You’ll also see a button labeled “Lab 0 checkoff”. Click this button to have your lab submission checked off and graded.

You should see a screen similar to this one, with a grade of 2 points for Lab 0:

Step 4: Use your anonymous ID located at the top right corner of the grading server to fill out this quick Diversity Survey.

• However, each question within the form is optional, and we will never tie this information back to your actual identity.
• We will only use this form to assess how diverse our student body is, and to check and correct for any bias in grading.
• We will delete your responses at the end of CS 300.

Congratulations, you’ve completed Lab 0 and are set up for CS 300!