| Home | Syllabus | Assignments | Resources | Piazza |
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.
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:
$ git statuswith no files showing up as modified, missing, or any other suspect behavior. 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.
You should make sure that your team repository has all the intended commits from both you and your partner.
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 either issue patches or make updates to the master CS161 repository. Patches are files created by diff or git diff that describe changes to files. Patches are "applied" using the patch program. More information on using patch will be provided with any patches that may appear.
To fetch patches from the staff OS/161 repo, you can run:
$ git fetch handout remote: Counting objects: 67, done. remote: Compressing objects: 100% (49/49), done. remote: Total 49 (delta 32), reused 0 (delta 0) Unpacking objects: 100% (49/49), done. From github.com:CS161/CS161-handout * [new branch] master -> handout/master $ git merge handout/master
If the remote repository "handout" doesn't exist in your git repository, you can add it like this:
git remote add handout git@github.com:CS161/CS161-handout.git
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 Git repository and push them to your partner.
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 -start (for example,asst1-start for assignment 1.) See Using Git for more information about tags and how to create them.
$ git tag asstN-start $ git push origin master --tags
You may use whatever document preparation tools you like to write your design documents. All we ask is that you submit them as either PDF or plain text. This expedites the process of reading them and providing feedback.
Note that plain text is a perfectly reasonable format and there is no need to include diagrams, charts, graphs, animations, or any other non-text elements. Sometimes a well-chosen diagram or two will be helpful; but be sure to spend your time on the content, not the presentation. (Diagrams in ASCII art are perfectly fine, for example.)
Please do not send Word documents, PowerPoint slides, dvi files, GIF, JPEG, PNG, 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.
Submit your design documents via git. Place the document in the directory os161/submit/asstN and name it asstN-design.txt or asstN-design.pdf. Make sure to do
git add submit/asstN/asstN-design.{txt,pdf}
so that git tracks the file.
Then you can commit it and push, and once you push it we can
pull from your repository to read, comment, and and grade.
It is also ok to email the design document to your TF. (But if you use both git and email, be sure the two copies you send are the same, or you indicate clearly in the email which one is to be used; otherwise we probably won't notice that they're different and it's unspecified which one will end up graded.
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. When you update your design document, explain what changes you made and why; the final design should reflect not only what your final design is, but how you got there and why. It is critical that you identify any people from whom you got advice or input on your design (e.g., your peer review partners). We will assume/know that you had TF input, but input from any source other than your TF or partner must be documented.
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 now represents about the tenth iteration of this process. Believe it.)
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, as with design documents, please submit PDFs.
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.
Please place your answers in a plain text file, usually named answers.txt in submit/asstN 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 submit/asstN directory of your repository as well. (It is easier for us if you send them as a separate file rather than incorporating them into the design document.)
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 such as more and less, editors such as vi or pico, and 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 os161/submit/asstN/ directory and commiting via Git.
Submitting Assignments You will submit your assignments simply by pushing all changes to your team repository and then tagging it with asstN-submit. Remember to push both your commits and the tags, using a command like
$ git push origin master --tags
Before you submit your assignment, be sure all your changes (and your partner's as well) are committed into Git and pushed to the Github Classroom repository. Changes that you do not commit do not exist as far as Git is concerned, and will thus not be submitted to your TF. Changes that you haven't pushed to the team Github Classroom repository likewise won't be seen and graded.
The best way to confirm that your system is behaving as it should is to create a brand new clone of your repository into a temporary directory (~/tmp/asstN, for example). 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/asstN # You have to create this directory before running configure. $ mkdir ~/tmp/root $ ./configure --ostree=$HOME/tmp/rootNote 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.
$ bmake $ bmake install $ cd kern/conf $ ./config ASSTN $ cd ../compile/ASSTN $ bmake depend $ bmake $ bmake 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 ~/src/root/sys161.conf ~/tmp/root/ # Need this to run the simulator. $ sys161 kernel "tt1; 1a; q" $ # ...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. When you're satisfied, remove ~/tmp or whatever temporary directory you were using.
Use Git to extract a diff of the changes you made in the course of the assignment. Diff the whole source tree between the asstN-start and the tree that you've tested and are about to tag and submit. Use the -w (don't consider indentation changes to be significant), -p (include C function names), and the -u (create a patch) diff flags.
For instance, you would do this:
$ cd ~/cs161/os161 $ git diff -w -p -u asstN-start
Read the diff to make sure it shows the changes you expect. If it does not, or you got errors from Git, perhaps your tags are missing or aren't attached to the right versions of the source files. If you need help, contact a TF.
Make sure that your repository has all the pieces that you need to submit. Each assignment should have a list of things you need to submit, but in general, you should submit:
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 asstN-submit (for example, asst1-submit for assignment 1.) See "Using Git" for more information about tags and how to create them. For example, to tag at the end of an assignment:
$ git tag asstN-submit $ git push origin master --tagsNote that if you are re-tagging you will need to tell git that you really mean what you said:
$ git tag -f asstN-submit $ git push origin master --tags
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.
When the grades for an assignment are ready, we'll commit the information to your submit repository, where you can pick it up by doing git pull.
For some material we may also hand back printouts with written comments - please pay attention to these, particularly when we mark up your code, as this feedback is time-consuming to generate.