(* README
 * Author: Frank Pfenning <fp@cs.cmu.edu>
 *)

-----------------------------------------------------------------------
Welcome to 15-411 F09!
-----------------------------------------------------------------------

This is some starter code for the L1 compiler you have to build for
the Lab1.  It contains a lexer, parser, translator, and even a code
generator, except that the code generator creates pseudo assembly
language with fictitious instructions and an unlimited number of
registers.  We took some care to use good style (according to the
instructor); you may consider this a model for your own coding.  Feel
free to modify any and all of this code as you see fit.

Bug reports to the instructor Frank Pfenning <fp@cs.cmu.edu> are
particularly welcome and will be noted in the extra credit category.

-----------------------------------------------------------------------
Java Notes
-----------------------------------------------------------------------
In this class we will be using Sun Java 1.6.0_10.  Please make sure your
code compiles under specifically this version on the lab machines
where it is the default.

If you develop your implementation on other machines, similar versions
of Java are likely to be compatible, but you should certainly check
your code on the lab machines.

Intel architecture and Java API documentation can be found at

  http://www.cs.cmu.edu/~fp/courses/15411-f09/resources.html

------------------------------------------------------------------------
Support Files
------------------------------------------------------------------------
The following are the support files for the L1 compiler

README               -- this file

Makefile             -- makefile for the compiler
                        For a quick test

    % make l1c          (generates file l1.jar)
    % bin/l1c --verbose ../tests/test1.c

	                should generate ../tests/test1.s in pseudo assembly

    % make clean        (removes generated files)
    % make TAGS         (creates file TAGS, for Emacs tags commands)

bin/l1c              -- the script that runs the generated jar file

------------------------------------------------------------------------
Source Files
------------------------------------------------------------------------
The following are the source files for the L1 compiler

All of the given code resides in the subdirectory edu/cmu/cs/l1, in accordance
with the Java package-naming convention. The repository also includes CUP and
JLex, which are Java parser and lexer generators.

absyn/
	 The absyn package contains all the classes for the abstract
	 syntax tree. For example, ASIntConstant.java contains code
	 for representing an integer constant in the AST. 

	 ** Important **
	 Observe ASStatement.java. You will see it implements an
	 interface called Visitable. This is part of a design pattern
	 know as the "visitor" pattern. Observe ASPrintAbsyn.java. You
	 will see this class implements Visitor. ASPrintAbsyn is going
	 to "visit" the nodes in the AST. One can accomplish this by
	 doing this,
	       ASPrintAbsyn printer = new ASPrintAbsyn();
	       ASStatement code = ...;
	       code.visit(printer);
	 The visit method in code will invoke the visitResponse
	 on printer, giving a reaction. The advantage of this method
	 is recursive algorithms can be performed on the AST without
	 those methods being bundled into the AST classes
	 themselves. Make sure you understand this method before
	 proceeding.

assem/
	Contains classes that represent an abstract assembly language
	instruction. These all take Strings for instructions, and are
	formatted with their register or memory values at the last
	stage of compilation.

codegen/
	This packagae contains an interface for a theoretical code
	generator. Any code generator you write (for x86, SPARC,
	PowerPC) will all implement this interface, making it somewhat
	portable for the rest of the compiler. The CodegenMain file
	will produce the assembler code without doing any sort of
	register allocation and print to stdout.

errormsg/
	Useful for producing errors. It tracks the line numbers of
	positions in the files and produces a uniform error msg. It
	also helps facillitate the use of GNU cpp for using #include
	and #define directives later on.

general/
       Constains the Visitor pattern interfaces as well as some
       utility stuff. Globals contains one interesting function,
       extFuntionName. In Cygwin, an external function needs a _ in
       front of it, so extFunctionName is applied to all foreign calls
       (not really needed until L2 and L3).

main/
       Contains the main compiler driving code. Processes the
       different modes to run under, etc.

parse/
       The simple.cup and simple.lex files describe the grammar and
       lexicon. The Parse file will run the parser and return the
       AST. ParseMain will print out the AST.

symbol/
       Intern rep of a String. Also provides a rudimentary symbol
       table.

temp/
       Contains classes for representing Temps. A Temp can have many
       attributes, and the TempMap sets up an interface for classes
       that are able to map Temps to String.

translate/
       Turns the AST into IR tree code. The main Translate classes are
       all Visitors. This illustrates the usefulness of this
       system. The end result of translation is a IRStatementList that
       can be sent to the code generator.

tree/
       All the classes for the Appel IR representation. The IRPrint
       class can be used to print out the IR.

x86/
       Contains 3 classes that implement x86 specific things. The
       FrameIntel implements the x86 frame. X86CodeGenerator produced
       TOY assembly now, but should be retargeted for
       x86. X86RegisterAllocator can be used to implement spilling
       rewrite code.
