SUBMITing, TARing and MAKEFILEs

(Please notice on-going changes at the end of the document)

PART I: Makefile
^^^^^^^^^^^^^^^^

You are asked to submit an assignment in electronic form, tar'ed and
with a makefile inside the tar'ed archive.  The following are
instructions on how to create and submit a proper file.

Once you have writen a solution to the problem stated in the
assignment, you will have several files which will be required to
build and test your solution.  For example you may be left with the
following files in your directory:

bst.c       -- file containing all BST functions
bst.h       -- header file describing interface to BSTs
main.c      -- main file with IO handling
a.out       -- an executable built by either GCC or cc
input.test  -- a sample input file

The first thing you need is to create a makefile.  Makefiles are files
which tell the system how to create a certain project.  In this case
the project is your assignment.  Makefiles can declare dependencies so
that the system knows which files need to be recompiled after one of
the source files have been changed.  In your case the project is
small, so you make the makefile very simple.  The following
instructions for makefiles will be VERY limited.  For more information
on makefiles run "man makefile" at a prompt on any ECF machine.

*************************************
IMPORTANT!!!!

The file you want to create will be called a1.
The compiler you want to use to create your file is cc.

*************************************

The general format for makefiles is:

result.file : dependency.1 dependency.2 .......
                command1
                command2
                command3
result.file is the file you want to create (in your case that is a1).
dependency.1, dependency.2, etc., are files which are required to
build result.file (in case of directory described above these would be
bst.c, bst.h and main.c).  command1, command2, command3, etc., are
commands which are used to create result.file from files listed as
dependencies.  For exmaple, makefile for directory described above may
look something like:

a1 : bst.o main.o
                                cc -o a1 bst.o main.o

main.o : main.c bst.h
                                 cc -c -o main.o main.c


It is important that the indent for the commands is a TAB, not a bunch
of spaces.  Your makefile won't work properly if that is not the case.

You can notice that a1 depends on bst.o and main.o, which in turn depend
on
main.c, bst.c and bst.h.  One of the purposes of makefiles is to
automate
this sort of dependencies - you can make files depend on files that will
be
generated during the make process, and make will stop if there are
problems
with generating any files.

This needs to be saved in a file called Makefile - with a capital
'M' - in the same directory as rest of the files.  Once you have your
makefile created and saved, you should try building your project using
it.  Run the following command:

skule.ecf% make

This will read your makefile and attempt to build your project.  If
everything went all right, you should see a new file in your directory
called a1.  Try running this file:

skule.ecf% a1

If everything went all right, you should a1 in your directory.  Test
this
file to make sure it works properly.  If you can't find a1 in your
directory look at what was printed after you ran make.  You should find
an
error describing what happened (either there was a problem with your
makefile or there was a problem compiling your assignment).  Fix the
problem and try again.

PART II: Test Files
^^^^^^^^^^^^^^^^^^^

The next thing you need is to create a tar file with the result of all
your test cases in input.test.  Assuming your sample input was saved
in input.test and you still have a1 in your directory, you'd run the
following:

skule.ecf% a1 < input.test > output.test

This command will run your progam (a1), use file input.test as input
(as if you typed it on the keyboard) and save the output to file
output.test (everything that would usually be displayed on the
screen).  After you execute this command you should have a new file
output.test in your directory.  Inspect this file to make sure that
the output is what you were expecting it to be.



PART III: Tar files
^^^^^^^^^^^^^^^^^^^

Next step is to create a tar file.  Tar files are files which hold
several other files inside.  The main difference between these and
programs such as PKZIP for your home PC is that tar doesn't compress
the files in the archive.

To create a tar file you need to run a program called tar, tell it to
create a new file archive, give it the new archive's file name and
list of files to put inside.  The syntax to do that is as follows:

skule.ecf% tar cf archive.tar file1 file2 file3 ...

tar is the program used to create a tar file.  cf will tell tar to
create a new file.  archive.tar is the name of the file that will be
created and file1, file2, file3, etc., are files that will be put
inside archive.tar.  For more info on tar, run "man tar" on any skule
machine.

*************************************
IMPORTANT!!!!

The archive you want to create will be called a1.tar
*************************************

Your tar file MUST include your source code, your test input and
output, your makefile and possibly a readme file with extra
explanations.  So in the example above to create a tar file a1.tar,
you'd run:

skule.ecf% tar cf a1.tar bst.c bst.h main.c Makefile input.test
output.test

After you're done you should have a file a1.tar which holds all the
necessary files to submit.


PART IV: Submit
^^^^^^^^^^^^^^^

To submit you will use a program submitcsc326f.  It takes two
arguments:

submitcsc326f assignment-num filename

Your assignment-num is 1.  To submit your program you should run:

skule.ecf% submitcsc326f 1 a1.tar

This will copy a1.tar to a repository on skule system and store it for
us to mark.

NOTE: 

(1) You may submit your program several times.  Every time you submit
your program (using submitcsc326f) the old version will be DELETED
from the repository and replaced with the new file.

(2) submitcsc326f will allow you to submit your program late.  It will
ask you if you're sure you want to submit your program late, and if
you say you do, it will again DELELTE old version of submited program
and replace it with new version.  We know the date and time of when
you submited your program so we WILL mark it late.

====================================

Additional Note: send email about this document to Shanon.




====================================

CHANGES: do not tar the files, submit them separately !

Michal just talked to phil poulos (ecf system manager) again, and he
said that students shouldn't tar their files.  instead they should
submit each file separately like so:

submitcsc326f 1 bst.c bst.h main.c
submitcsc326f Makefile
submitcsc326f input.test output.test

and so on.  they can submit many files at a time and when they submit
new files only the ones with overlapping filenames will change.  

Please note that the corrected/updated version of the instruction will
be posted to the newsgroup soon.

--Shanon