CS161 - Harvard University - Preparing Assignments for Submission

DIVISION OF ENGINEERING AND APPLIED SCIENCES
HARVARD UNIVERSITY

CS 161. Operating Systems

Matt Welsh
Spring 2005

Preparing Assignments for Submission
[CS161 Home Page]

Introduction and Advance Considerations

There are potentially a lot of details involved with submitting CS161 assignments. The purpose of this document is to serve as a single point of reference for all the issues.

These are things you should attend to even before you start working on each assignment.

CVS Consistency

Before you start working, make sure both you and your partner have committed all your changes associated with the previous assignment. You should both be able to do:

  % cvs update

with no files showing up as `M' (modified). It is not necessarily wrong to have modified files you don't want to commit, but you should be aware of their existence and the nature of the modifications in question. You should also have thought about why you don't want to commit them yet/at all and be able to justify your decision.

Official Patches

If bugs are discovered in OS/161 in the course of the semester (we hope there won't be any, of course) the course staff will issue patches. Patches are files created by diff or cvs diff that describe changes to files. Patches are "applied"' using the patch program. More information on using patch be provided with any patches that may appear.

At this point, between assignments, if there are any OS/161 patches issued by the course staff that you have not already applied, you should apply them. Don't forget to commit the resulting changes to the CVS repository.

Tagging Your Repository

Now tag your repository. This will allow you to refer to the version of your code that existed before you started working on a particular assignment. Use the assignment name and -begin (for example,asst1-begin for assignment 1.) See "Using CVS" for more information about tags and how to create them.

You are now ready to begin work.

Submitting Design Documents

Formatting

To the extent practical, please write your design documents as plain text files so they can be sent to your TF as ordinary e-mail. This expedites the process of reading them and providing feedback.

If you want to make diagrams, charts, graphs, or any other graphical element, feel free to use the tool of your choice, but please send the results as PostScript or PDF. Please do not send Word documents, PowerPoint slides, dvi files, GIF, JPEG, or other raster image files, pic(1) source, gnuplot scripts, etc., etc.-while we may be able to process some or all of these, we may not, and dealing with them may delay your feedback. If in doubt, ask your TF.

ASCII art and/or hand-drawn sketches are fine, too.

Submitting

For assignments 2-5, your design document should be e-mailed directly to your TF by the design document due date. Keep a copy and also submit an updated version of it along with the final assignment materials.

Updating Design Documents

Typically your design will change between the time you finish writing the design document and the time you finish the assignment. Please update your design document accordingly.

There are two ways to do this. One is to modify the document itself, so that when you're done you have a design document that perfectly matches the code and appears to have been written with prescient knowledge of the implementation difficulties you ran into. If you do this, please submit, along with the final assignment, both the original design document and the modified one, and please include a quick summary of the changes you made.

The other way is to leave the original document the way it is and add running commentary and description as you discover that you need to alter the design. If you do this, please mark clearly where the original design ends and add a quick outline of the final design at the end.

Either of these methods is perfectly reasonable for CS161. You need not do both.

Note that it is unreasonable to expect your initial design to be perfect; unless you're superhuman you should expect to make at least a few modifications as you build the code. This is a natural consequence of writing software of a kind you haven't written before. (In fact, even after you write the same kind of software two or three times, you'll still not write a perfect design for the third or fourth time, because you keep learning more about the problems and issues. The OS/161 thread system represents about the sixth or seventh iteration of this process.)

Submitting Performance Analysis

Your performance analysis is essentially a short lab write-up and should be treated accordingly. You may want to include tables or graphs, in which case you should feel free to use your favorite tools, but, like with design documents, please submit as PostScript or PDF.

Please don't try to construct quantitative graphs in ASCII. Also, if you use Excel, beware that XY graphs do not necessarily produce correct X axes and your results will be confusing.

Submitting Written Work (e.g., code reading, problems, etc.)

Please place your answers in a plain text file. You need not include the questions, but please do try to label each answer clearly with the number of the question to which it belongs.

After assignment 1, code reading questions are due along with the design document and should be e-mailed to your TF. Please also submit a copy with your other assignment materials when you finish the assignment.

Submitting Script Output

Several assignments ask you to provide scripts demonstrating your system running or showing a log of doing various things.

You can make a script of a session by using the Unix program script. It saves a copy of everything you type and everything you see into a file called typescript, which you should rename suitably and submit along with the other assignment materials.

When you run script, it starts a new copy of the Unix command interpreter program (shell) and starts logging. It will continue to log until you exit that shell, which you do by typing exit.

That is: when the script is supposed to be done, type exit. Please don't forget to do this.

Also note that script is not all that smart. It doesn't interpret control codes of any kind; they go directly into the script file, where your TF will have to look at them.

For this reason, please avoid running programs that generate a lot of control codes. This includes pagers like more and less, editors like vi or pico, essentially all other text-screen programs. Also, please disable color-ls and any other similar highlighting tools while running script.

If you need to edit while preparing a script, do it in another window.

Once you've finished making the script, please edit it and remove backspace characters (as well as the characters backspaced over) and the garble resulting from any editor sessions you may have inadvertently included. (Please do not edit anything else.)

Script files should be submitted along with other assignment materials using the submit utility.

Submitting Releases and Diffs

To submit your source code, we require that you make a release of your version of OS/161. A release is a specific version of the system packaged for distribution to other people, in this case your TF. You will make the release by taking a particular snapshot of your CVS repository.

Consistency

Before you begin to make the release, be sure all your changes (and your partner's as well) are committed into the CVS repository. Changes that you do not commit do not exist as far as CVS is concerned, and will thus neither be part of your release nor submitted to your TF.

Tagging Your Repository

First, tag your repository. This will allow you to refer to the specific version of your code that you are submitting. Use the assignment name and -end (for example, asst1-end for assignment 1.) See "Using CVS" for more information about tags and how to create them.

Preparing Diffs

Use CVS to extract a diff of the changes you made in the course of the assignment. Diff the whole source tree between the "begin" and "end" tags for the assignment. Use the "-w" (don't consider indentation changes to be significant), `"-N" (include new files), and "-u" ("unified" output format) diff flags.

For instance, for assignment 1, you would do this:

  % cd ~/cs161/src
  % cvs diff -wuN -rasst1-begin -rasst1-end > asst1-diff

Read the diff to make sure it shows the changes you expect. If it does not, or you got errors from CVS, perhaps your tags are missing or aren't attached to the right versions of the source files. If you need help, contact a TF.

Also, please remove any extraneous or valueless gunk that shows up in the diff, like changes in generated files (such as depend.mk) or purely visual changes to code (like repositioning braces). Do not edit out anything with semantic significance; if in doubt, leave it in.

Preparing a Release

Go to a temporary directory. Extract a release of your system from CVS using cvs export. Use the tag you just made to tell CVS what version to export. For assignment 1:

  % cvs export -rasst1-end src

This creates a clean copy of the system without CVS control files. CVS will leave the copy in a directory named src. By convention, however, software source releases normally unpack into a directory whose name consists of the package name and version number. So, rename the src directory to your group name and the assignment. If your group name were "ocelot", for assignment 1 you'd use ocelot-asst1.

Now, create a tar/gzip archive for "distribution".

  % tar -cvzf ocelot-asst1.tar.gz ocelot-asst1

Obsolete versions of tar may not support -z to create a compressed archive directly. In that case, the equivalent is:

  % tar -cvf - ocelot-asst1 | gzip -c > ocelot-asst1.tar.gz

Move the compressed tar file somewhere else and delete the temporary directory (including the cvs export'd source tree).

Test Your Release

It helps everyone if you take an extra fifteen minutes or so to double-check your release.

Create yet another temporary directory. Let's suppose it's ~/tmp, and that, again, you're submitting assignment 1.

Go into this directory and unpack your tar file.

  % cd ~/tmp
  % tar -xvzf ~/somewhere/ocelot-asst1.tar.gz
  % # Or, do the following....
  % gunzip -c ~/somewhere/ocelot-asst1.tar.gz | tar -xvf -

Run the configure script for the tree, telling it to install in ~/tmp/root. (This way the test won't overwrite your working root.)

  % cd ocelot-asst1
  % ./configure --ostree=$HOME/tmp/root

Note that you need to use $HOME instead of ~ because it's not at the beginning of the argument.

Now, build the system and then configure and build the kernel or kernels associated with the assignment.

	% make
	% cd kern/conf
	% ./config ASST1
	% cd ../compile/ASST1
	% make depend
	% make
	% make install

Go to ~/tmp/root, boot the kernel, and run one or two simple tests to make sure nothing is catastrophically wrong and that the code you've got is, in fact, the solution for the assignment you're submitting.

	% cd ~/tmp/root
	% sys161 kernel `tt1; 1a; q'

If it blows up unexpectedly, go back to your main work area and try to duplicate and fix the problem. Commit any necessary changes. Before trying again, move the CVS tag. (See "Using CVS" to find out how to do this.) If you don't move the CVS tag, the next cvs export will fetch the same broken version you already tried once. Then go back to Section 7.3, above, and repeat.

When you're satisfied, remove ~/tmp or whatever temporary directory you were using.

Collect Everything Together

Make sure you have all the pieces you need to submit. Each assignment should have a list at the back. In general, you should submit:

The diff from your CVS repository showing the changes you've made.
The .tar.gz file containing the release of your operating system.
Any session scripts requested by the assignment.
A copy of your sys161.conf file.
Your design document, possibly both original and updated versions, along with any diagrams.
The answers to the code-reading questions, as you mailed them to your TF along with the design document.
Answers to any written exercises.
A performance analysis report, if the assignment requires it.
Any additional release notes or other commentary you wish to include that don't seem to belong in the design document, if any, in a README file.

Running submit

To run submit, place all the items you wish to submit in a single directory, which you should name after the assignment (asst1, asst2, etc.). Then run

	% submit cs161 N ~/wherever/asst1

where ~/wherever is the directory with the submission items and N is the number of the assignment (0-5), not the full assignment name.

Please run submit by the assignment due date and time. If you're a few minutes late, we won't charge you a late day. (Abuse of this leeway will result in its disappearance.)

Make sure exactly one person (no more, and obviously no less) in your group submits; it doesn't matter who.

Hardcopy

Please do not submit a hardcopy or printout of anything for your assignment. We would really like to save paper here and printing out design docs and code is wasteful. Instead, we'll print what we need for grading and hand it back to you with comments on it.