Lab 0: Preliminaries

Objectives

After completing this lab, you should be able to:

Log in to the course server
Clone your lab repository
Use make to build a lab
Commit (and version control) your changes
Submit your work by pushing your changes to the remote repository

ada.cs.iit.edu

While you may choose to code and test on your own computer, all of your final labwork must be verified to build and run correctly on the course server located at ada.cs.iit.edu.

Connecting to the server requires the use of a secure shell (ssh) client such as putty for Windows or the command-line clients for OS X and Linux. Your username on the system is the same as your my.iit.edu login, and your password is posted on Piazza.)

Upon successfully logging in for the first time, you will be prompted to change your password -- pick a secure one and don't forget it!

The Lab Repository and Git

We will be using the Git distributed version control system for the purposes of lab file dissemination, version control, and submission of your work.

Before you can start using it for labwork on ada, however, there are a few things you need to do to set things up correctly.

1. Introduce yourself to Git

Replace John Doe and jdoe@iit.edu with your own information, and run the following commands after logging in to ada:

git config --global user.name "John Doe"
git config --global user.email jdoe@iit.edu

2. Clone the course repository

You should at this point have received an invitation by e-mail to join BitBucket and access a private repository created for you. After creating an account on BitBucket, you'll be provided with a "clone" URL, which should look something like git@bitbucket.org:michaelee/cs351-spring12-jdoe.git (the semester and username will be different).

Run the following command -- substituting your own URL -- to clone the repository into a directory named cs351:

git clone git@bitbucket.org:michaelee/cs351-spring12-jdoe.git cs351

You will need to type in your BitBucket password every time you interact with the remote repository. To get around this, you can register your SSH key with BitBucket. One has already been associated with your account on ada, and the following command should take care of the registration (again, replace 'jdoe' and 'secretpassword' with your own information):

curl --request POST --user jdoe:secretpassword https://api.bitbucket.org/1.0/ssh-keys/ --data-urlencode "key@$HOME/.ssh/id_rsa.pub"

Using Git

Within the cs351 directory you'll find two subdirectories: examples and labs. The examples directory contains sample code that we'll go over together during lecture, and the labs directory contains files for all the lab assignments you'll be working on over the course of the semester.

As you make modifications to lab files, you should periodically commit your changes to the local repository. Each commit is tracked by Git, and can be associated with a log message describing the reason for the changes.

Git allows you to do very useful things with commits -- for instance, you can:

review the associated log message for any commit
"reset" your working files to the state of the last (or any previous) commit
examine the differences between a file in your "working tree" (i.e., what you're actively working on) and a previously commited version of that file -- this lets you see all the recent changes you've made
"branch" your repository so that you have separate paths of development (this allows you, for instance, to try different approaches to a given problem and version control all of them)

Git Magic is an good reference and introduction to working with Git. I highly recommend you spend some time figuring out the basics -- it just might save you many hours (or days) of frustration.

When it comes time that you wish to submit your work, you will push your commits from the local repository to the remote repository. You can push as many times as you like, so if you push your work before a lab deadline but commit a few more bugfixes afterwards, just push again!

There are some other advantages to using a distributed version control system, too:

If you accidentally delete your repository on ada but recently pushed all your changes, simply clone your handin repository. Presto -- automatic backup!
If you want to tinker with your lab on a different computer (without logging on to ada), you can simply commit and push your work from ada, then clone your handin repository on your own computer. When you'd like to work on ada again, push your changes from your computer, then pull them on ada.

Essential commands

The following is a list of some essential Git commands you'll be using, based on the discussion above:

git status: Shows the status of your working tree -- among other things, this lists the files that you've changed since the last commit.
git diff filename: List all the changes you've made to the named file since the last commit.
git commit -a: Commits all modified files, after prompting you to enter a commit message in a text editor (the commit takes place after you save your message and exit the editor).
git push: Pushes your commits in the local repository to the shared, remote repository. This essentially submits your work so we can get to it. You can do this as many times as you want, and we'll only look at the most recent version (made before the submission deadline, of course).
git pull: Pulls changes from the remote repository to your local repository. You should do this periodically (at least once before starting each lab), as we add feedback files to your handin repository after you submit your work for grading.
git checkout filename: Updates filename in the "working" tree to the last committed version -- you would do this, say, if you completely botched up the file and want a fresh copy. Don't do this is you have changes to the file that you don't want to lose!
git help: Accesses a comprehensive (but sometimes cryptic) online help. You can do git help command for help with the specified command. E.g., git help commit gets you more information on the commit command.

Moving Along

For this lab you will be working in the labs/0_prelab subdirectory of your repository.

In this directory you will find two files:

Makefile: describes how the lab is to be built (compiled)
hello.c: C source code for the "hello world" program

Building the Lab

While you can certainly compile the "hello.c" file manually (by invoking the GNU C compiler with the command gcc), there's an easier way. Invoking the make command with the name of a target defined in the Makefile will carry out the appropriate actions for you. Invoking the make command with no arguments will carry out the default action, which is usually to compile the lab files and build an executable binary.

Try this now -- run the following command in the labs/0_prelab directory:

make

This should compile "hello.c" and generate the "hello" binary. You can execute it as follows:

./hello

Running make again at this point will not rebuild the binary, as it is already newer than the source file on which its based. If you were to edit the "hello.c" file at this point (try it -- change the message that's being printed) and save the file, running make again would initiate a rebuild.

Sometimes, when you're running into weird problems with a build, it helps to delete all the intermediate build files and recompile from scratch. You can do this by first using the "clean" target, which deletes all the intermediate build files, then follow it with make again. Try the following (the semicolon just separates the two commands on a single line):

make clean ; make

Making Some Changes

I'm not looking for much here -- the point of this lab is really to make sure you can log in, clone your repository, edit files, and commit/push some changes. But you need to pretend to do some work. So.

Change the hello.c program so that it prints, on separate lines:

Your name
Your Banner CWID
A joke. (Seriously -- we can use some entertainment while we grade).

Here's some sample output:

1. John Doe
2. A23581321
3. There are 10 kinds of people in the world: those who understand binary,
   and those who don't.

Make sure your program compiles and runs correctly, and proceed to ...

Submitting Your Work

If you're satisfied with all your changes, you're ready to commit them to the local repository along with a commit message. The next command will do this (you can change the message, if you like):

git commit -am "Added required information to hello.c for prelab"

You should get output that looks something like this:

[master 4da2cf1] Added required information to hello.c for prelab
1 files changed, 3 insertions(+), 1 deletions(-)

Note that in future labs you should be committing your work fairly often — certainly more than just the one time after you've completed the lab. That way, you'll not only have a log of your work, you'll also be able to rollback to a given version should you discover that you introduced a bug or altered code you wish you hadn't in more recent commits.

After you've committed your work, you can now push your changes to the central repository. The following command does that:

git push

You'll get output like this:

Counting objects: 9, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 562 bytes, done.
Total 5 (delta 2), reused 0 (delta 0)
To git@bitbucket.org:michaelee/cs351-spring12-jdoe.git
   02b0e91..0de3a77  master -> master

Which tells you that you successfully sent your changes over the network to your handin repository. Note that if you try to run git push when there aren't any pending commits to be pushed, it will simply tell you that everything is up-to-date on the server. (Try it!)

That's it. Congratulations! You now have a cloned, up-to-date repository that you'll be doing all your work in, and you know how to commit your changes (for version control) and how to push your commits to the central server so that we can get to them.

Feel free to play around a bit more in the prelab directory -- you can modify your files, check the output of git status, and even commit some more changes and push them (just make sure your code compiles correctly).

Grading

In most labs you'll find a grading section where I discuss my grading rubric/rationale. Note that all labs are hand-checked, so you won't receive an automated response after handing in your work.

There isn't much to say here for this lab. If your hello.c file compiles without errors, runs, and produces the required output, you will receive full credit. If your file doesn't compile, or it doesn't produce the required output, you won't receive any credit.

Git Usage Summary

This section briefly summarizes the steps you should take when working on a lab. You may find it helpful to refer back to this section when working on future labs, particularly if you're new to this Git stuff.

Before starting a new lab, do a git pull to make sure that your local repository is up-to-date with any changes we made to the central one.
As you work on the lab, every time you finish making a substantial set of changes (to one or more files) do a git commit -a to record your changes to version control.
When you are ready to submit your work (or if you just want to back it up or work elsewhere), commit all recent changes and do a git push to push all pending commits to the remote repository.

CS 351 : Systems Programming