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.
|VirtualBox||Free virtual machine software|
|Vagrant||Easier virtual machine management|
|Git||Version control software|
|GitHub||Online code storage and version control|
Windows Tip: Vagrant works on Windows, but some of the commands below (particularly
vagrant ssh) may not work out of the box. If you run into trouble, please post on Piazza and we’ll help you get set up!
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.
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.
Warning! VirtualBox version needs to be 6.0.14 or older, since that is the latest Vagrant supports.
Task: Install VirtualBox and Vagrant. Once installed, you can confirm that they were installed properly by running the following commands on your terminal. They should print the version number:
vboxmanage --version vagrant --version
Windows Tip: Note that the
vboxmanage command will not work on Windows — instead, you need to pass in the absolute path to where you installed Vagrant. For example, if you installed
C:\Program Files\Oracle\VirtualBox then you would run:
C:\Program Files\Oracle\VirtualBox\VBoxManage.exe --version
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:
Task: Do the following to set up your Virtual Machine:
cs131) where you want to set up your VM.
touch Vagrantfileinside the directory.
Vagrantfile: CS131 Vagrantfile
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!
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.
Task: Turn on your VM, ssh into it, and explore. Then, exit the VM (
exit, or Ctrl-D) and turn off your VM.
Make sure whenever you’re running Vagrant commands you are inside the directory you made for your VM.
vagrant up # turns on your VM vagrant ssh # connects to the VM
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.
“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
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.
Task: Go into your
cs131 folder, and create a file and a folder. Then, go into your VM, delete that file, and add a file to the folder. This is so you get a feel for what is going on, since you’ll be using this on a regular basis!
Outside of the VM, in your
touch cool_file mkdir awesome_folder
vagrant up #(if it wasn't already) vagrant ssh
Inside the VM:
cd /vagrant ls # print the file and dir we just created
rm cool_file cd cool_folder touch even_cooler_file exit # or just CTRL-D
Back outside the VM:
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!
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.
Task: Within your VM, use
apt to install the following packages:
build-essential- compiler tools (make, gcc, etc.)
clang- another C/C++ compiler with better error messages
clang-format- for auto-formatting your code
gdb- for debugging
You will need to use
sudo, which runs commands with elevated privileges.
$ sudo apt install <package>
sudo apt install build-essential sudo apt install clang sudo apt install clang-format sudo apt install gdb
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):
vimis 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
vimpackage, but we also recommend neovim (package
emacsis 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
emacspackage in the course VM.
make) to analyze and understand project context.
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:
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.
Task: Within your VM, set your name and email in Git.
git config --global user.name "Jennifer Stevenson" git config --global user.email "firstname.lastname@example.org"
If you are not already signed up to GitHub with your
brown.edu email address, add it to your profile so that GitHub knows to correctly attribute commits to your username.
Optional: you can cache your GitHub credentials to avoid entering them in each time.
git config --global credential.helper store
Now, take a look at some beginning Git tutorials.
Then, complete this section of the Earth Lab Version Control Intro tutorial. (Run the commands in section 3 inside your VM).
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.
Task: Accept the GitHub Classroom assignment for projects and labs, then clone each repo into your VM.
/vagrantinside your VM)
git clone email@example.com:csci1310-s20-projects-YOURUSERNAME.git git clone firstname.lastname@example.org:csci1310-s20-labs-YOURUSERNAME.git
YOURUSERNAME is your GitHub username. The above commands assume that you have registered an SSH public key with GitHub; if you haven’t, try using
https://github.com/csci-1310... instead of the
Once you cloned the repository, you should see the
strvec in the projects repo, and the
lab1 directories in the labs repo. These are the only assignments we’ve released so far; you will add others later.
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.
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.
Committing and pushing:
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.
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.
If you only recently registered or you’re shopping the course but haven’t registered, you won’t have an account yet. In that case, please complete this form and wait until you receive your credentials. We will create accounts based on the form entries at 8pm every day.
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.
Filling out the survey is required and your grade for Lab 0 and Lab 1 will depend on whether you filled this out (even if you passed the checkoff on the grading server!).