-----------------------------------
RRR   EEEE   AA	  DDD   MM MM  EEEE
R  R  E	    A  A  D  D	M M M  E   
RRR   EEE   AAAA  D  D	M M M  EEE 
R  R  E	    A  A  D  D	M   M  E   
R  R  EEEE  A  A  DDD	M   M  EEEE
-----------------------------------    	       	       	    
				   
##############
# AUTHORSHIP #
##############

This CSUB (subset of C) compiler is written by Liz Bennet and Luke Lovett
as part of the CS331 course at Oberlin College during the Spring of 2012.


##############################
# BUILDING THE CSUB COMPILER #
##############################

There is a Makefile included with the sources, which should make building the
compiler quite easy. Do not use the Makefiles present in each of the package
directories, but rather invoke the primary Makefile in the project root (i.e.,
`csub/Makefile` ).


##################
# CODE GENERATOR #
##################

Our code generator goes through two separate stages: generating three-address
code, and generating real assembly from that. Our three-address code generator
("IntermediateGenerator.java") seems to be working great! It outputs code that
is already very close to the assembly we want.

Interesting design decisions include the fact that we decided to have two stages
to our generator: three-address code, then assembly code for MIPS. Additionally,
our compiler has the ability to print to STDOUT instead of a file (if no output
file is specified). Also, all variables and temps are maintained DIRECTLY ON THE
STACK, making register management very easy ;)

In our earlier submissions, arrays, pointers, and contorl structures were either
not fully implemented, needed further testing, or were buggy. This situation
has been remedied. Arrays and pointers have been tested both on their own
and with pass-by-reference. Our generator will allow assignments like:

int *a;
a = 4;

But this will probably crash in Mars. Just like real C! (i.e., allowing the
programmer to do things that will break). Doing this:

int *a;
*a = 4;

Will also break, because there hasn't been any space allocated for 'a' (i.e.,
'a' is NULL). You can basically only use pointers to pass primitives by
reference (since we have no way of allocating space).

Testing was done with the files in generator/tests. We were also using tests
in the /tests directory as well to test our code. Assembly debugging was done
in MARS.


IMPORTANT! - To run the generator, run: 
--------------------------------------
$ java generator.Generator <input> <output>

If neigher <input> or <output> are specified, STDIN and STDOUT are used. If only
one is supplied, it is assumed to be the INPUT file, and STDOUT is used to print
out assembly code. It is sometimes useful to run the code generator printing out
debugging information as it goes. Debugging information includes:

1. An annotated syntax tree
2. A table of three-address code for the input program
3. The symbol table, specifying what identifiers reside where on the stack.

This is especially useful when you want to do printing, since there is no direct
way in the CSUB language to print something. Instead, you must branch to the
'printint' subroutine in the assembly code. The definition of this is included
in the header to all programs generated by this CSUB compiler. 


####################
# MORE INFORMATION #
####################

We are using SVN to track versions of our code. You might consult the version
log to see finer details on the changes we have been making over time to our
code.


##############
# HONOR CODE #
##############

We have adhered to the Honor Code in all parts of this assignment.