Nachos Project Mechanics

Assignments

Assignments are to be done in teams of two or three. To register your team have each team member sign the following contract and submit it to Dr. Qiao

----------------------------
Nachos Project Team Contract
----------------------------

We agree to work together for the entire semester.

We understand the academic dishonesty policy and agree to be
jointly responsible for all work submitted.

We understand that we will get one team mark regardless of
who does what work.

We agree to email cs3mh3@ritchie.mcmaster.ca a complete
description of any marking concerns no later than one week
after work is returned.



__________________________________________________________________________
signature, name, student number and McMaster email


__________________________________________________________________________
signature, name, student number and McMaster email


__________________________________________________________________________
signature, name, student number and McMaster email



-------------------------------------------------------

What to submit?

Each assignment will ask you to add functionality to a teaching operating system called NACHOS. You are to implement and test your solution. For marking purposes however, we want you to describe:

non-obvious features correct designs have

minimal set of necessary test cases

how to implement your designs (code snips with context)

Points to remember:

Keep your design simple and your submissions less than two printed pages (60 characters per line * 60 lines per page) for each item in the assignment.

The burden of communication is on you. Your mark will suffer if your write-up is confusing or hard to mark.

If you use information from other sources state what and where you found it.

Don't try to code, compile, and test your implementations unless you are confident that you have a perfect design. You will get 60% of credits if you have a perfect design even your program does not compile. If the design is poor, you will not get a good grade, even your program compiles (no syntax errors).

When to submit?

Assignment deadlines are flexible. Each team starts with an extension of 48 hours, for use on any assignment during the semester, in any increment, as long as the total amount of lateness does not add up to more than 48 hours.

How to start svn?

Goto https://websvn.mcmaster.ca/cs3mh3/
Use your CAS Unix login and password to authenticate

How to submit using svn?

Suppose your group id is groupA, then your "groupRepository" for assignment1 is

     https://websvn.mcmaster.ca/cs3mh3/groupA

At the beginning, only original Nachos code is in your "groupRepository". You need to add assignment1, assignment2 and so on in your groupRepository to submit your assignments this term.

In the following part, we use groupA as your group id to illustrate. You should replace groupA with your group id.

First check out Nachos code from your group repository to your home directory in your cas account, say birkhoff, and add assignment1 folder in your groupRepository.

    birkhoff>svn co https://websvn.mcmaster.ca/cs3mh3/groupA
    birkhoff>svn mkdir assignment1
    birkhoff>svn import groupA/nachos-4.02/code https://websvn.mcmaster.ca/cs3mh3/groupA/assignment1
    birkhoff>rm -fr groupA

Second, before establishing a link between the assignment1 in your group repository and your cas account, to organize your files, create a subdirectory cs3mh3/assignment1 in the home directory in your cas account and change to that directory:

    birkhoff>mkdir cs3mh3
    birkhoff>cd cs3mh3

Then check out assignment1 folder in your group repository to cs3mh3/assignment1 in your home directory:

    birkhoff>svn co https://websvn.mcmaster.ca/cs3mh3/groupA/assignment1

Now that you have established a link between assignment1 in your group repository and cs3mh3/assignment1 in your home directory, you can work on your cs3mh3/assignment1 and upload/download from/to your group repository.

Whenever you modify or create files, you need to compile your program:

   birkhoff>cd ~/cs3mh3/assignment1/code/build.sun
   birkhoff>gmake depend
   birkhoff>gmake

To run your program:

   birkhoff>./nachos

To upload your latest version to repository so your partners can share:

   birkhoff>cd ~/cs3mh3/assignment1
   birkhoff>svn commit --message "whatever you want to say."

To add a new file, for example, README1, to your group repository:

   birkhoff>svn add README1 groupRepository

To make sure your upload is complete, check:

   https://websvn.mcmaster.ca/cs3mh3/groupA/Assignment1

To download the latest version from your group repository:

   birkhoff>cd ~/cs3mh3/assignment1
   birkhoff>svn update

Some useful commands:

To delete object files created during last compilation:

   birkhoff>cd ~/cs3mh3/assignment1/code/build.sun
   birkhoff>gmake distclean

To copy a file from one location of repository to another:

   birkhoff>svn copy source destination --message "whatever"

where "source" and "destination" are the full paths of source and destination files, such as
https://websvn.mcmaster.ca/cs3mh3/groupA/Assignment1/fileName

To delete a file from repository:

   birkhoff>svn delete fileName --message

again, where "fileName" is the full path of the file.

To list the difference between your cas account and group repository:

   birkhoff>svn diff

If you see differences and want to upload changes, use commit.

Put a README in your group repository for each assignment. A README should include:

Names of all team members;

How late assignment is, and how much extension time left;

The files that you modified or created for each part of the assignment;

Your design ideas;

Output of your test.

For more information about subversion, please visit

   http://svnbook.red-bean.com/nightly/en/svn-book.html#svn.intro

Two copies of Nachos 4.02 code are reserved at Thode Library.

To help you understand what's going on we have road-maps at

    http://www.cas.mcmaster.ca/~qiao/courses/cs3mh3/index.html

How to build Nachos

Change to directory code/build.sun
type: gmake depend
type: gmake

A few .o files and nachos executable will be generated. Try running nachos.

Whenever you change or add files, you need to re-gmake. You always re-gmake in build.sun directory. DO NOT re-gmake in other directories.
If you only change files, you just gmake in build.sun directory.
If you add new.h or and new.cc files, you should update Makefile before gmake depend followed by gmake. For example, if you add mailbox.h and mailbox.cc in threads directory, you should add ../threads/mailbox.h under THREAD_H, add ../threads/mailbox.cc under THREAD_C, and add mailbox.o under THREAD_O. Note that there is no subdirectory name under THREAD_O. It is always safe to run gmake depend followed by gmake.

To re-build from scratch, go to build.sun and type: gmake distclean.

You may read the header of build.sun/Makefile, except that you should use gmake instead of make.