Computer Science 372
Operating Systems

 Denison
Syllabus Schedule Supplements Email

Preparing Assignments for Submission

Introduction and Advance Considerations

There are potentially a lot of details involved with submitting cs372 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.

Subversion 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:

  % svn status
with no files showing up as `M' (modified) (or '!', missing, or potentially any other flags). 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 svn 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 Subversion 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 Subversion for more information about tags and how to create them.

  % svn copy https://tashi/svn/<username>/trunk https://tashi/svn/<username>/tags/asst<X>-begin
Submitting Design Documents

Formatting

Write your design documents using LaTeX. If you want to make diagrams, charts, graphs, or any other graphical element, you can EZDraw on the Macs or another tool of your choice and then include them in the LaTeX document and submit only the single PDF document that results.

Submitting

Your design documents should be put into your ~/cs372/submit/asst<X>/ directory in a subdirectory called design, which should get added to the grading repository. These will be checked at the appropriate due date/time. We expect this document to be updated on the way to the final assignment completion. I should be able to do either a 'make' to get the design pdf, or to do a pdflatex, or, if I need further instructions, I should see a README.

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. 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 LaTeX document and include in your sources. 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.

Code reading and other questions due along with the design document should be placed in the appropriate file in your ~/cs372/submit/asst<X> directory.

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 by placing them in the ~/cs372/submit/asst<X> directory and commiting via Subversion.

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 exporting a particular snapshot of your Subversion repository.

Consistency

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

Test Your Release

Before you tag or submit, you should make sure that you have committed everything and that your system will load and boot extracted from svn export.

Go to a temporary directory. Extract a release of your system from Subversion using svn export. Doing an export of trunk and testing it before tagging is a good way to avoid retagging. If you don't have a group name yet, use your user name below:

  % cd ~/tmp/ # Create this directory if it doesn't exist
  % svn export https://tashi/svn/<username>/trunk <groupname>-asst<X>

This creates a clean copy of the system without Subversion control files. Subversion will leave the copy in <groupname>-asst<X>.

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 ~/tmp/<groupname>-asst<X>
  % mkdir ~/tmp/root # You have to create this directory before running configure.
  % ./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 ASST<x>
	% cd ../compile/ASST<x>
	% 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
  % cp ~/cs372/root/sys161.conf ~/tmp/root/ # Need this to run the simulator.
  % sys161 kernel
  % # ...etc..., run any other tests as appropriate.

If it blows up unexpectedly, go back to your main work area and try to duplicate and fix the problem. Commit any necessary changes, and then try again, blowing away the tree you exported and redoing the export above. When you're satisfied, remove ~/tmp or whatever temporary directory you were using.

Tagging Your Repository

Once you are satisfied you have a stable version of the code ready to submit, 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 Subversion" for more information about tags and how to create them. For example, to tag at the end of an assignment:

  % svn copy https://tashi/svn/<username>/trunk https://tashi/svn/<username>/tags/asst<X>-end
Note that if you are re-tagging you probably need to remove the original tag first. To re-tag an assignment: 
  % svn rm https://tashi/svn/<username>/tags/asst<X>-end
  % svn copy https://tashi/svn/<username>/trunk https://tashi/svn/<username>/tags/asst<X>-end

Preparing Diffs

Use Subversion to extract a diff of the changes you made in the course of the assignment. Diff the whole source tree between the asst<X>-begin and asst<X>-end tags for the assignment. Use the -w (don't consider indentation changes to be significant) and -u ("unified" output format) diff flags.

For instance, you would do this:

  % cd ~/cs372/src
  % svn diff -x -wu https://tashi/svn/<username>/tags/asst<X>-begin https://tashi/svn/<username>/tags/asst<X>-end > ~/cs372/submit/asst<X>/ asst<X>-diff

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

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

The final step is to package up a release of your system, i.e. a gzipped tarball that we will use for testing your submission. You will use your tagged tree above to perform this step: 
  % cd ~/cs372/submit/asst<X>/
  % svn export https://tashi/svn/<username>/tags/asst<X>-end <groupname>-asst<X>
  % tar -czf <groupname>-asst<X>.tgz <groupname>-asst<X>
After you tar your release, be sure to remove the ~/cs372/submit/asst<X>/<groupname>-asst<X> your svn export created: 
  % rm -rf <groupname>-asst<X>
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 Subversion repository showing the changes you've made.
  • The .tgz 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 instructor 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.

Submitting

To submit, we expect that you will commit a directory containing the necessary files for the assignment into https://tashi/svn/<username>/submit/asst<X>. Gather your things together in a directory ~/cs372/submit/asst<X>, then add and commit the directory. (You should have checked out a copy of https://tashi/svn/<username>/submit into ~/cs372/submit/ in ASST0).

Please commit your files 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.