S-Q Utilities

This document describes several UNIX tools that you will need to use in order to complete your S-Q assignments. These are non-standard utilities, so even if you are already familiar with UNIX you should read this material carefully.

Parts of this document were originally written for CS50 by Professor Margo Seltzer and members of the CS50 course staff.


Communicating Via Email

There are many tools designed to let users communicate via the computer. The tool that we will be using most heavily is email. The mail program lets you send and receive messages with users in this class, at Harvard, or nearly anywhere in the world. You will often find email (electronic mail) the easiest way to contact your teaching fellow or professor. Please learn how to use the mail system effectively; you will find it extremely useful.

Please check your email frequently (especially when you are working on your homework) in order to see whether we've sent out any changes to the assignment or added any hints.

There are a variety of different mail reading programs available on the science center machines. The most common is pine. pine is easy to learn, and has a number of useful features. User Services (in the basement of the Science Center) has documentation and tutorials for pine.

The most basic mail program is called mailx, and is described in Todino and Strang's "UNIX in a Nutshell". Refer to the man pages and the book for instructions on using mailx.

There are two mailing lists set up for this course:

s-q@eecs.harvard.edu
The s-q mailing list sends mail to the course staff and all of the students. It can be useful for setting up study groups or any other sort of announcement to the class as a whole. (Remember that you must work individually on the assignments, so posting questions or discussions of the assignments is inappropriate. Such mail should be sent to libsq@fas, as described below.)

Note that for this mailing list, the entire email address needs to be specified; just using s-q is not sufficient.

libsq@fas.harvard.edu
The libsq mailing list sends mail to the S-Q course staff. It is useful for asking questions about the assignments or just generally getting in touch with the professor or a TF.


Machines to Use

The UNIX machines that we'll use for this course are named ice (for Instructional Computing Environment). There are actually several identical machines named ice1 through ice4; when you log in to < ice, you will be redirected to the least busy of these. The machines should behave completely identically, so there is no need to worry about which you are logged in to.

The ice machines are not physically accessible to users (i.e. they are not located in a public place). A number of alpha workstations are available in the basement of the Science Center, however. These machines are named ws1 through ws38 and are configured to be functionally identical to the ice machines. If you log into one of these workstations, there is no need to telnet to one of the ice machines.

You should be able to telnet to the ice machines from anywhere on the internet-- simply telnet to ice.harvard.edu. (You can also connect via ssh, if your computer supports it, and I recommend this because of the added security and privacy it provides.)

Note that the fas computers are intended for general use (mostly email) and should not be used for doing your programming assignments. The fas computers are not configured identically to the ice computers.

In order to use the Harvard UNIX systems at all, you will need an account. You should have been given an account when you registered for Summer School, and this account will suffice for all of your coursework. If you did not receive an account, please contact the User Services people in the basement of the Science Center ASAP about getting one (or contact me, if you have difficulty obtaining an account).

When you go to log into the alpha workstations directly from the console, there will be a window displayed where you enter your logname and password. When you log in, the window manager will start up automatically. You can click on the small terminal icon to create new windows. Clicking on the background will give you a menu that will allow you to log out.


Turning in your work

We will ask you to submit both paper and on-line copies of your homework. The paper copies make it easier for your Teaching Fellow to grade, and the on-line copies let us run your programs. The program that lets you submit your homework electronically is called submit. The submit program sends a copy of your homework to the course staff so that they can grade it. You can submit as often as you like, but only the last two submissions are kept.

To run submit:

  1. Make sure you have placed all the files you desire to submit in the appropriate directory (generally ~/Q/asstN, where N is the number of the assignment). Remove any extraneous files that you don't want to hand in (usually a make clean will clean up any scratch files created by the compiler).

  2. Go to the directory directly above the directory where your assignment files are. For example, if all your S-Q materials are in ~/Q/ and you are submitting assignment 2, which you have stored in ~/Q/asst2, then you should cd to ~/Q.

  3. Type the command:

    	submit cscisq N ~/Q/asstN
    	
    Replace X with the number of the assignment (1-6) and For example, if your files for assignment 2 are in ~/Q/asst2, then the appropriate command to submit your assignment 2 would be
    	submit cscisq 2 ~/Q/asst2
    	
    Note that the full path of the directory is required. (The submit program contains a bug that prevents it from working properly with relative paths.)

  4. submit will print out a bunch of messages on the screen. Most of them are pointless, but keep an eye out for specific errors or instructions. For example, when submitting asst2, you may see messages like:

    	Ok, submitting the files in /home/e/l/ellard2/Q/asst2
    	Creating temporary directory /usr/lsys/submit/ellard2...
    	Copying assignment files to /usr/lsys/submit/ellard2...
    	Submitting cscisq assignment 2...
    	Temporary files removed.
    
    	Successful submission!  
    	

    Almost all of these messages can be safely ignored. The exception is that if the last line doesn't say that the submission was successful, then it probably was not, and you will have to submit again. The other messages should give some indication what the error was.

You may re-submit your work as often as you like. Each time you run submit, the previous submission is overwritten.


checkin and checkout - Keeping Track of Versions of Your Files

Throughout this course, you will be creating files and modifying them. Occasionally, you will make changes to a file and later regret having done so. In order to make it simple to get back to previous versions of your files, we strongly encourage you to use a source code control system. In general, source code control systems allow you to maintain a history of the changes you make to a file, so that you can "undo" sets of changes or compare different versions.

The system that we will be using for this class is called RCS (Revision Control System). RCS will keep track of all old versions of a file while you are creating a new version. If you like the changes you have made, and you wish to make them permanent, you can use the checkin command to do so. Once you have done that, RCS believes that most recent copy of the file is the "real" one. If, instead, you decide that you do not like the changes you made, you can retrieve any previous version of the file from RCS using the checkout command. Also, if you are trying to figure out what has changed since an earlier version (because your program used to work and now it doesn't), you can use the rcsdiff command to show you what has changed.

You can find out all the details of RCS by looking at the man pages for rcs, ci, co, rcs diff, rlog, and others. In the meantime, we have created some simplified versions of these commands that are described here.

checkin filenames
checkin tells RCS that you have a new version of the specified files. RCS will preserve them for future reference. When you execute checkin, RCS starts up an editor so that you can add comments about why you are checking in each file and any other information you want to record about this revision of the files. You will find it most helpful if you write very precise and detailed comments when you check things in, so that later when you need to find a specific version of a file, it is easy to identify.

The editor that checkin uses by default is vi. If you prefer to use a different editor, then make sure that your environment variable EDITOR is set to the name of the editor that you prefer. For example, if you prefer emacs, add the line:

	setenv EDITOR emacs 
	
to your ~/.cshrc file (if you haven't done so already).

checkout filenames
checkout retrieves the that last copy of files that you checked in. checkout can also be used to retrieve previous versions of files, by specifying the name or revision number that you want to check out.

rlog filename
rlog displays a list of all the revisions of a set of files. This will print out all the comments that you added when you ran checkin.

rcsdiff filenames
rcsdiff displays the differences between the version of each file that you have checked out and the last version that you checked in. If you want to look at different versions than the most recently checked in one, consult the man page for instructions.


Using make

The programs you will write for this class are often constructed from several different files. As your programs become more complex, it will become difficult to keep track of all the different files. Fortunately, UNIX provides a tool that does this for you. This tool, make, allows you to define rules for how to perform a job and then uses those rules to do the job for you. For example, if you have a large software program, it will usually consist of many source files (sometimes called ".c" files). Each of those source files might use some number of include files (sometimes called "header" or ".h" files). In order to create a program that the computer can run, you must compile each ".c" file to create ".o" files and then link the ".o" files together to create the final program. Furthermore, each time you modify one of those ".h" files, you will have to recompile all the ".c" files that use it. You can imagine that this gets tedious pretty quickly.

So you don't have to do each of these steps manually, the make utility can keep track of all your ".h" and ".c" files and generate the commands that must be executed to compile and link them. It uses a set of rules to figure out how to do this. The language in which to write these rules is cryptic and difficult to understand, even for experienced programmers. Fortunately, make already knows all of the rules that you need for this class. We will usually give you a Makefile (set of rules for make to use) so all you will need to do is type

make program
Sometimes we will ask you to change the names of the files listed in the Makefile. In any case, at this point in your programming career, you need not concern yourself with the details of make. However, you should have an understanding of what it is doing for you. If you desire to learn more about it, there are lengthier descriptions available, as well as several decent reference books.


S-Q Course Account