CS5600 Lab0: Setup and tools

We are going to use git and Linux virtual machine for distributing and collecting assignments.

Challenge: you will see challenges in labs. They are optional. If you successfully finish them, you will get extra credits.

GitHub

If you don’t have a GitHub account, sign up for one here. You only need a Free plan for the labs.

Setup a Linux VM

In this course, all of our programming assignments will be assessed on a Linux virtual machine (VM). You can think of a virtual machine as a way to run a particular operating system (in our case, an instance of Ubuntu) on top of another operating system (the one that controls your laptop or desktop).

We recommend VirtualBox, which runs on Windows, Linux, and MacOS and has been successfully used in this class for many years.

You have two options to build the class VM:

Option 1: use pre-built CS5600 VM image.

CS5600 staffs have prepared a ready-to-use VM image for you. To choose this option:

download and install VirtualBox: be sure to download the package that is appropriate for your system. Once it has downloaded, install it by double clicking on the installer and following the prompts. The default settings for installation are generally the right ones.
download the pre-built VM image from Canvas->Files->CS5600.ova
run the VM by double clicking the image file or importing the image in the VirtualBox.
(optional) Watch this video from 13:15, you will see how to run a terminal and update packages (you don’t have to update the packages). The video also explains some basics of Linux and C.

Option 2: install you own VM from scratch challenge

Again, you need to first download and install VirtualBox.
Next you need to download the target operating system—Ubuntu 20.04.x LTS by going to https://ubuntu.com/download/desktop. This will download an .ISO file to your computer. An ISO file is an image of the data on an optical disc, and it will appear to the virtual machine as a (virtual) CD/DVD-ROM drive.
Finally, follow along with the video here to setup and configuration of an Ubuntu virtual machine. You will need to pause the video as you go along.
Get your extra credits by running uname -a in the terminal, taking a screenshot, and upload it to the assignment “lab0-challenge”.

Notes:

If you are using Apple M1 chip (check here), you’re unable to install VirtualBox. You need to find an Intel/AMD x86 machine to install VirtualBox. If you’re unable to find one, see option 3 below.
For Mac users, you may face a permission problem when installing VirtualBox. See the solution here. Or, if you see “The Installation Failed”, see here.

Option 3: use qemu to run Ubuntu NEW

This option is for students who use Apple M1 chip. We thank the Khoury system team and CS3650 staff for their help and sharing.

install brew: if you haven’t installed brew, install it.
install QEMU: open Terminal on your Mac, and run
```
  $ brew install qemu
```
download script: go to Canvas->Files->qemu.sh and download the file

download CS3650 VM: create an empty folder and run the file qemu.sh

  $ mkdir ~/cs5600/
  $ mv YOUR_DOWNLOAD_DIR/qemu.sh ~/cs5600/
  $ cd ~/cs5600/
  $ chmod +x qemu.sh
  $ ./qemu.sh

(after a while) you should be able to see a window named “QEMU” with a prompt “cs3650-guest login:”
QEMU VM login: find the username and password printed on the Terminal (the one you run $ ./qemu.sh); or find them in the file qemu.sh (by $ cat qemu.sh).

Below are in the terminal of the QEMU window (after your login). Note: you cannot copy paste here.

install ssh by running:

  $ sudo apt install ssh keychain ssh-server

enable ssh with password: you should modify file /etc/ssh/sshd_config and change the line PasswordAuthentication no to PasswordAuthentication yes. Here is one way with nano:
```
  $ sudo nano /etc/ssh/sshd_config
  // change PasswordAuthentication no => yes
  // save and quit
```
restart the ssh server:
```
  $ sudo service ssh restart
```

Note: the Ubuntu installed in QEMU is a minimum version. If you need any tools, install it by sudo apt install (also Google is your good friend).

Finally, we can ssh to the Ubuntu inside QEMU by running cmd in your Mac’s terminal:

$ ssh -p5600 vagrant@localhost

This will ask for password that you have seen in your terminal or qemu.sh.

This completes the installation of QEMU VM for M1.

Of course, besides VirtualBox and QEMU, if you have an Ubuntu installed, you can use it as well. But, notice that we may need you to install packages and update environments in later labs. We strongly recommend you to use a VM, so that you don’t have to mess up your working environment.

See some useful links/references about Linux command line and C in the end of this page¹.

Git and GitHub

What is git?

Git was developed by Linus Torvalds for development of the Linux kernel. It’s is a distributed version control system, which means it supports many local repositories which each track changes and can synchronize with each other in a peer-to-peer fashion. It’s the best widely-available version control system, and certainly the most widely used. For information on how to use git, see:

For the workflow in GitHub:

GitHub Guides: Hello World

Cloning the lab0 repository

Please click the GitHub Lab0 link on Canvas homepage to create your own private clone of the lab0 repository; this clone lives on (is hosted by) GitHub. Once that clone exists, you will perform a further clone to get that private repository onto your devbox. You’ll do your work on your devbox, and then push your work to the GitHub-hosted private repository for us to grade.

Here’s how it should work.

Click the link.
Log in to GitHub.
Provide a name.
The link should automatically clone the repository. For instance, if your username name was foobar, you should now have a repository on GitHub called NEU-CS5600-21fall/lab0-foobar.

Teaching GitHub about your identity

The easiest way to access GitHub repositories is using an SSH key, a secret key stored on your CS5600 VM that defines your identity. Follow the steps below to create a key for your virtual machine.

Enter your VM: double click the image or start the VM in VirtualBox
Open Terminal.
(i) for students who use CS5600 pre-built VM: enter your name and email when being asked.
(ii) for students who build their own VMs: run ssh-keygen -t rsa -b 2048 and follow the instructions.
- Press enter to use the default file path and key name (should be ~/.ssh/id_rsa).
- Choose a password or leave it empty.
This creates your ssh keys, which live in the directory ~/.ssh. Your public key is in the file ~/.ssh/id_rsa.pub.
Run cat .ssh/id_rsa.pub to display your public key.
Copy your public key (that is, select the text on the screen, and copy it to the clipboard).
In GitHub, go to your profile settings page (accessible via the upper-rightmost link–this looks like a bunch of pixels for new accounts). Select “SSH and GPG keys” and hit the “New SSH key” button. Then copy and paste the contents of your ~/.ssh/id_rsa.pub (from the VM) into the “Key” section. Give the key a sensible title, hit the “Add SSH key” button, and you’re good to go.

Creating a local clone

Once GitHub knows your SSH identity, you’re ready to clone your lab repository and start doing work! Here’s how to get a local clone of your private repo on your machine:

Enter your VM and open a terminal

Configure your git “identity” as it shows up in commits:

 $ git config --global user.name "FIRST_NAME LAST_NAME"
 $ git config --global user.email "YOUR_@COLLEGE_EMAIL"

Clone your lab0 repo:
```
 $ cd ~
 $ git clone git@github.com:NEU-CS5600-21fall/lab0-<Your-GitHub-Username>.git lab0
```
Note that the git@github.com:... can be obtained on GitHub by clicking the “Clone or download” button. You want to clone using SSH, not HTTPS, so you might need to click “Use SSH”.

Look at the files in the repo:

 $ cd ~/lab0/
 $ ls

You should see:

 Makefile    main.c    slack.txt

Exercise 1 compile and run hello world.

compile and run the helloworld
$ cd ~/lab0/
$ make
$ ./hello
Now you should see
hello world

Saving changes while you are working on labs

As you modify the skeleton files to complete the labs, you should frequently save your work to protect against laptop failures and other unforeseen troubles, and to create “known good” states. You save the changes by first “committing” them to your local lab repo and then “pushing” those changes to the repo stored on github.com.

$ git commit -am "saving my changes"
$ git push origin

Note that whenever you add a new file, you need to manually tell git to “track it”. Otherwise, the file will not be committed by git commit. Make git track a new file by typing:

$ git add <your-new-file>

After you’ve pushed your changes by typing git push origin, they are safely stored on github.com. Even if your laptop catches on fire in the future, those pushed changes can still be retrieved. However, you must remember that doing git commit by itself does not save your changes on github.com (it only saves your changes locally). So, don’t forget to type git push origin.

To see if your local repo is up-to-date with your origin repo on github.com and vice versa, type git status.

Exercise 2 your first commit. hello CS5600.

go to the lab0 folder cd ~/lab0/
open the file main.c using your favorite editor, for example, nano main.c (nano is a text editor)
go to line 4 (using arrow keys) and update “hello world” to “hello CS5600”
save and exit the editor (if nano, type Ctrl-X and press y and press enter)
compile and run new code, make; ./hello. You should see hello CS5600.
commit, git commit -am'first commit to CS5600'
push to github.com, git push origin
You should see something like:
 Counting objects: ...
 ....
 To ssh://github.com/NEU-CS5600-21fall/lab0-<username>.git
  7337116..ceed758  main -> main

Finally, submit your work

Submitting lab0 consists of two steps:

Executing this checklist:
- Fill in slack.txt with (1) your name, (2) your NUID, (3) slack hours you used, and (4) if you took the challenge.
- Make sure you have finished Exercise 2, namely you have done git commit -am'first commit to CS5600' and git push origin
Actually commit your lab (with timestamp and git commit id):
- Get the git commit id of your work. A commit id is a 40-character hexadecimal string. You can obtain the commit id for the last commit by running the command git log -1 --format=oneline.
- Paste the commit id (the hexadecimal string) to Canvas. In Canvas, there is an assignment named “lab0”. You should paste only the commit id (the entire string).
- Note: You can submit as many times as you want; we will grade the last commit id submitted to Canvas. Also, you can submit any commit id in your pushed git history; again, we will grade the commit id submitted to Canvas.

NOTE: Ground truth is what and when you submitted to Canvas.

A non-existent commit id in Canvas means that you have not submitted the lab, regardless of what you have pushed to GitHub—we will not grade it. So, please double check your submitted commit id!
The time of your submission for the purposes of tracking lateness is the timestamp on Canvas, not the timestamp on GitHub.

This completes the lab.

Acknowledgments

Some links were borrowed from prior CS5600s (2020fall and 2021spring). A large portion of this writeup was borrowed from Mike Walfish’s CS202, which further borrowed materials from Harvard’s CS61, Jinyang Li’s CS201, and Aurojit Panda’s 3033.

- “The Linux Command Line,” 5th edition, William Shotts http://linuxcommand.org/tlcl.php.
- The Linux command line for beginners: https://ubuntu.com/tutorials/command-line-for-beginners#1-overview.
- Programming in C, Fourth Edition, Stephen G. Kochan, Addison-Wesley Professional, 2014 (available online through NEU library).
- C Tutorial: https://www.cprogramming.com/tutorial/c-tutorial.html.
↩