« Back to the main CS 131 website

Lab 0: Getting Set Up (Course VM & Git)

Due February 4, 2020, at 8:00PM

Introduction

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

The main tools we’ll be using are Vagrant, a convenient way to manage virtual machines, 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 go to 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 131 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.

Virtual Machine Setup

Your computer is probably running Mac OS X, Windows, or Linux. These different operating systems all come with different libraries and preinstalled software. In order to make sure we all work in the same environment, we will use a Virtual Machine (VM) running the Linux-based operating system, Ubuntu. Our grading server also runs a Linux-based OS, so if your code works in the VM, it will work on the grading server.

Software

There is a lot of software out there to run VMs (e.g., VMWare, RedHat, Hyper-V, or Parallels). This software allows the OS inside the VM to believe that it’s running on a physical computer, even though we are actually running it within an OS on another computer.

For CS 131, we will be using VirtualBox because it’s free. On top of this, we’ll be using another piece of software called Vagrant, which facilitates the VM setup process.

$ vboxmanage --version
$ vagrant --version

> C:\Program Files\Oracle\VirtualBox\VBoxManage.exe --version

Vagrant Setup

When setting up a VM you have to provide a copy of the operating system you want to run, along with any other settings you want the VM to work with. Lucky for us, Vagrant handles all this setup and configuration. All we need to do is specify what settings we want in a single file, called the Vagrantfile. For this course, we’ve created a Vagrantfile for you that specifies three things:

1. Which operating system we want to use (Ubuntu Bionic Beaver).
2. Enable X-11 forwarding in case you want to use the VM with GUIs, akin to FastX.
3. Restart SSH and update package lists each time we turn it on. (Nice to have, but not strictly necessary.)

Note: You should skim over all the options in the Vagrantfile, to see what is else is available to configure. Feel free to play around with these!

Using the VM

Once you set up your VM, you will want to turn it on and access it. Since it’s essentially an entirely separate computer, you will need to use SSH to connect to it, much like you do with the department computers. Unlike regular SSH, however, you won’t be connecting over the internet, but directly through Vagrant.

$ vagrant up      # turns on your VM
$ vagrant ssh     # connects to the VM

vagrant@ubuntu$ exit     # exit ssh (VM is still on)
$ vagrant halt           # turns off your VM

Note: Your VM will remain on and running in the background until you run vagrant halt. That said, you don’t need to turn off the VM each time you finish using it; it’s common to leave it on for weeks or months at a time.

Shared Folders

“If my VM is a separate 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 me!)

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. Vagrant allows us to use a similar approach to access files on our VM.

Inside of the VM, there is directory called /vagrant. This directory is actually a mount of your cs131 directory (or whatever you decided to call it), and any changes you make in one will be seen in the other.

$ touch cool_file
$ mkdir awesome_folder

$ vagrant up   #(if it wasn't already)
$ vagrant ssh

vagrant@ubuntubionic$ cd /vagrant
vagrant@ubuntubionic$ ls # print the file and dir we just created

vagrant@ubuntubionic$ rm cool_file
vagrant@ubuntubionic$ cd cool_folder
vagrant@ubuntubionic$ touch even_cooler_file
vagrant@ubuntubionic$ exit # or just CTRL-D

$ ls # should just show cool_folder
$ cd cool_folder
$ ls # should show even_cooler_file

Note: Each time you enter your VM, you’ll most likely want to cd straight into /vagrant. To avoid having to do this every time, feel free to add cd /vagrant as the last line to your .profile file. This file, located in /home/vagrant, is run every time you ssh into your VM, so cd /vagrant will be run automatically when you enter!

Installing Additional Packages

Hurray! You’ve set up your VM, and you’re ready to start using it. However, since you freshly installed the operating system, you will be missing some important tools we’ll be using throughout the semester. You will need to install tools both to build (or compile), and debug your code.

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. We’ll use this tool to install everything we need.

$ sudo apt install <package>

$ sudo apt install build-essential
$ sudo apt install clang
$ sudo apt install clang-format
$ sudo apt install gdb

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 131, 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 131.

You can edit your source code inside the course VM, or on your normal operating system. Recall that the /vagrant folder inside the VM is a mount of your local cs131 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 in the /vagrant directory! You can then compile, build, and run your assignments inside your VM. This is the power of mounting !

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

Simple editors (you can install the first two in the course VM via sudo apt install):

• 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. In the course VM, it can be installed via the vim package, but we also recommend neovim (package neovim).
• 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. It is available via the emacs package in the course VM.
• 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.

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.

$ git config --global user.name "Jennifer Stevenson"
$ git config --global user.email "jennifer_stevenson@brown.edu"

$ 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.

$ vagrant ssh

$ git clone git@github.com:csci1310-s20-projects-YOURUSERNAME.git
$ git clone git@github.com:csci1310-s20-labs-YOURUSERNAME.git

Once you cloned the repository, you should see the strvec in the projects repo, and the lab0 and lab1 directories 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 VM. Also make sure you are working inside /vagrant, so your files are accessible to your editor.

$ 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 131 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 131.

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

i’m done