Link Search Menu Expand Document
CS3650

Lab1: Setup and tools

The first part serves as a warming-up phase for you to familiarize yourself with the environment and tools you will use this semester. The second part helps you practice coding in the C programming language. If you know C, this part will help you remember; if you don’t know C, this is an excellent opportunity to learn C, an elegant language.

There is a lot to read but not too many lines of code to write. Quote from the Labs page, “if a lab is at first confusing even in its instructions, please don’t be discouraged; understanding the instructions is part of the work of the labs!”

Part 1: Setup and tools

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

Section 1: GitHub

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

Section 2: 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 (with x86 CPUs) and has been successfully used in this class for many years;
  • VMwmare Fusion Player, if you use Apple machines with M1/2/3 chips. (How do I know if I’m using M1/2/3 chips? Check here.)

You have two options to start your Lab1:

Option 1: use VirutalBox CS3650 VM image (X86 CPUs).

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

  1. 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.
  2. download the pre-built VirtualBox VM image. The link and instructions are on Canvas homepage. This is a zipped file. You need to unzip before use.
  3. run the VM by double clicking the image file or importing the image in the VirtualBox.
  4. Note: you can find VM’s sudo password on Canvas homepage.
  5. (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.

Notes:

  • If you are using Apple M1/2/3 chips, you need to choose option 2 (see 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 2: use VMware Fusion CS3650 VM image (ARM CPUs).

This option is for students who use Apple M1/2/3 chips.

  1. register a free Personal User License of VMware Fusion Player 13. Go to VMware Fusion Player; select “License & Dowload” tab; click “create an account” (if you don’t have one); follow the instructions to create a VMware account; login your account; go to VMware Fusion Player again to get your Personal User License.
  2. on the same page, download and install VMware Fusion Player 13 by clicking “Manually Download” under tab “License & Download”.
  3. download the pre-built VMware VM image from OneDrive. The link and instructions are on Canvas homepage. This is a zipped file. You need to unzip before use.
  4. run the VM by double clicking the image file or importing the image to the VMware Fusion Player.
  5. Note: you can find VM’s sudo password on Canvas homepage.
  6. (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.

Of course, besides VirtualBox and VMware Fusion Player, if you have an Ubuntu/Debian 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.

note (01/16) XenOrchestra is now discontinued. If you don’t have your own machine, you can also use Khoury’s XenOrchestra.

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

Section 3: 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:

Cloning the lab1 repository

Please click the GitHub Lab1 link on Canvas homepage to create your own private clone of the lab1 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 (your VM). You’ll do your work on your devbox, and then push your work to the GitHub-hosted private repository for us to grade.

Here is how it should work.

Exercise 1 clone the lab on GitHub

  1. Click the GitHub Lab1 link on Canvas homepage to create your Lab1 clone on GitHub.
  2. Log in to your GitHub.
  3. Provide a name.
  4. The link should automatically clone the repository. For instance, if your username name was foobar, you should now have a repository on your GitHub called NEU-CS3650-labs/lab1-foobar.

Teaching GitHub about your identity

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

Exercise 2 submit your public key to GitHub

  1. Enter your VM: double click the image or start the VM in VirtualBox/VMware Fusion Player.
  2. Open Terminal.
  3. Run $ ssh-keygen -t rsa -b 2048 (don’t copy the $ sign) 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.
  4. Run cat .ssh/id_rsa.pub to display your public key.
  5. Copy your public key (that is, select the text on the screen, and copy it to the clipboard).
  6. 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 is how to get a local clone of your private repo on your machine:

Exercise 3 clone a local copy of the lab

  1. Enter your VM and open a terminal
  2. 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"
  3. Clone your lab1 repo:
     $ cd ~
 $ git clone git@github.com:NEU-CS3650-labs/lab1-<Your-GitHub-Username>.git lab1

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

  4. Look at the files in the repo:
     $ cd ~/lab1/
 $ ls

    You should see:

     debug.c  hello.c  Makefile  slack.txt

Make sure everything works

Next, compile and run a hello program.

Exercise 4 hello world!

  • compile and run the helloworld
$ cd ~/lab1/
$ gcc -o hello hello.c
$ ./hello
  • Now you should see
hello world!

GCC (gcc in the above example) is a widely used compiler. In the above command, -o specifies the output file (namely, hello) and hello.c is the source file to be compiled. See a quick introduction of gcc here. In this course, you don’t have to be an expert of gcc. We will provide compiling supports for labs. (Nevertheless, having some understanding of how gcc works is helpful.)

Part 2: C language and debugging

This part of the lab will give you practice on C and debugging.

Try to compile a program debug:

$ cd ~/lab1/
$ make

make is a system to organize compilation. When you run make, the compilation system will look for a file named Makefile and executes the rules within. Take a look at our simple Makefile which compiles the program debug (you can open it using your favorite text editor). We put comments to explain things. Again, you don’t have to be an expert of make, and here is a quick introduction.

Section 4: Fixing a syntax error and a typo

After running make, you will see some errors. This is because the code has a syntax error; thus, it cannot be compiled.

Exercise 5 Fix two errors.

  1. Next, you need to open file debug.c. Use the compiler’s error message to determine what’s wrong (a syntax error).
    Hints:
    • Note that the debug.c:18:5: ... in the message indicates an error in the file name (debug.c) and the line number (18).
    • You might see slightly different error messages due to different compiler versions.
    • The error can be on the adjacent lines of the report line number.
  2. After you fix the syntax error, the code will compile. Try make again:
    $ make

    Now, you should be able to compile but with a warning message debug.c:10:12: warning ....

  3. Run debug. You will see:
    $ ./debug
double a number (10) is (0)
debug: debug.c:21: main: Assertion `num + num == doub_num' failed.
Aborted (core dumped)

    Though our code compiled, but it was not correct. It failed on an assertion (num + num == doub_num). Read debug.c to fix this problem and let the program pass the assertion.
    Hints:

    • Warning information is useful.
    • This error is a typo. You should be able to fix the problem by changing only one line of code.

After fixing the two errors, you should be able to see:

double a number (10) is (20)
Pass!

Aha! Our code passes the assertion.

Section 5: playing with gdb

Run gdb: Use the GNU debugger, or gdb to run the program:

$ gdb debug
(gdb)

Set breakpoints: One thing that you might want to do is to set a breakpoint before the program begins executing. Breakpoints are a way of telling gdb that you want it to execute your program and then stop, or break, at a place that you define. Use the following command to set a breakpoint at the main function:

(gdb) b main
Breakpoint 1 at 0x11a7: file debug.c, line 17.

Run the program: Then use gdb’s command run to actually start the program (this is the general pattern in gdb: one invokes the debugger, perhaps sets a breakpoint, and then starts the program with run):

(gdb) run

Backtrace: The program will be stopped when it reaches the breakpoint. At this point, you will be presented with gdb’s command prompt again. To see the “call stack” (or stack trace), which is the list of functions that have called this one—literally, the stack frames on top of the current one—you issue backtrace or bt for short:

(gdb) bt

Experienced developers will often ask for a stack trace as step 0 or 1 of understanding a code problem. Get in the habit of asking gdb to give you a backtrace.

Continue running: To make the program continue running after a breakpoint, use continue, or c for short:

(gdb) c

Step through the code: Of course, if you just c every time you hit a breakpoint, then you will lose control of the program. You often want the command next, or n. Now, start over, by $ gdb debug, (gdb) b main, (gdb) run and run

(gdb) n

This “executes” the next line of code, for example executing an entire function. (The command step executes a single line of C code. There is little difference between step and next unless you are about to enter a function. step steps into the function; next “steps over” the function.)

Inspect the values of variables: In gdb’s command prompt, the program is stalled. You can query the program’s current global and local variables with the print command, or p for short. For example,

(gdb) print num
$1 = 10

This means that variable num holds a value 10.

Aside: you can check local variables’ names using:

(gdb) info local

Section 6: Saving changes by committing

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 6 commit and push.

  1. go to the lab1 folder cd ~/lab1/
  2. commit your modifications git commit -am"my CS3650 first commit"
  3. push to github.com, git push origin

  4. You should see something like:

     Counting objects: ...
 ....
 To ssh://github.com/NEU-CS3650-labs/lab1-<username>.git
  7337116..ceed758  main -> main

Finally, submit your work

Submitting consists of three steps:

  1. Executing this checklist:
    • Fill in ~/lab1/slack.txt with (1) your name, (2) your NUID, (3) slack hours you used, and (4) acknowledgements.
    • update (01/17) run make clean within your lab folder (~/lab1/).
    • Make sure that your code build with no warnings.
    • Make sure you have added (git add) all files that you created.

  2. Push your code to GitHub:

     $ cd ~/lab1
 $ git commit -am 'submit lab1'
 $ git push origin 

 Counting objects: ...
  ....
  To ssh://github.com/NEU-CS3650-labs/lab1-<username>.git
   7337116..ceed758  main -> main

note (01/13) Submission procedure is subject to change. Please stay tuned.
note (01/14) Submission procedure updated; now you should submit to Gradescope.

  1. Actually submit your lab via Gradescope:
    • Navigate to https://www.gradescope.com/ and click on log in.
    • Select login with “School Credentials” and select “Northeastern University”.
    • Enter Northeastern SSO login information and you should be able to log in to your gradescope account.
    • Now, on Canvas, go to the CS3650 course and click on “Gradescope 1.3” from the left navigation bar. You would then be asked to accept the course invitation after which you can access the course on Gradescope.
    • On Gradescope, select the lab/assignment you wish to submit and click on “Upload Submission”.
    • You would then be asked to upload a zip file consisting of the files the lab/assignment specifies.
    • After uploading the zip file, the autograder will evaluate your submission and based on it provide a score for your submission.
    • After the manual grading process is performed by the TAs, your final score for the lab/assignment will be released.

This completes the lab.

Acknowledgments

Some links in Part1 were borrowed from prior CS3650s (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.

  1. ↩