MiniJava-Compiler
=================

A compiler for a [small subset](http://www.cambridge.org/resources/052182060X/MCIIJ2e/grammar.htm) of java.

The compiler was written as the main project in an undergraduate [compiler course](http://gee.cs.oswego.edu/dl/csc444/).  
Minijavac parses Minijava source code, reports syntax and semantic errors, and checks to ensure that variables are initialized before they are used.  
If the source code is error free, java bytecodes(class files) are generated in the current working directory.  
As a language addition, minijava developers can use the power operator(2<sup>3</sup> ~ 2**3).


Run
---

The jar file can be found [here](https://github.com/csaroff/MiniJava-Compiler/raw/master/minijavac.jar)

minijavac requires java 1.8 to run.  
Minijava source code can be compiled as follows:

    java -jar minijavac.jar [source-file-name]

The generated byte code is backwards compatible with java 1.1 and will run on any version of java.
	
	java [main-class-name]
    
Overview
--------

Compilers operate in three main stages:

1. Parse source files to generate a [parse tree](http://en.wikipedia.org/wiki/Parse_tree).  Report any [syntax errors.](http://en.wikipedia.org/wiki/Syntax_error)

2. Traverse the parse tree, building a [symbol table](http://en.wikipedia.org/wiki/Symbol_table) from the source code and reporting all [semantic errors](http://en.wikipedia.org/wiki/Programming_language#Semantics).

3. Generate code in the target language(java bytecode in this case)

### Parsing and Syntax Analysis ###

To parse minijava source code, a [parser]() was generated with the Antlr4 [parser generator](http://en.wikipedia.org/wiki/Compiler-compiler) tool.  Antlr generates a parser in java for the given minijava grammar.
The parser attempts to generates a parse tree given some minijava source code. 
If any syntax errors are encountered during parsing, an error message is generated [underlining]() the offending tokens.
If there are no syntax errors, the parser builds a parse tree and the compiler proceeds to semantic analysis.  

### Static Semantics and the Symbol Table ###

Semantic analysis proceeds in the following fashion.

1. A symbol table is constructed be traversing the parse tree.  During this phase, the program is checked for:
    1.  [Duplicate klasses]()
    2.  [Cyclic inheritance errors]()
    3.  [Declaration before use]()
2. The program is [type checked]() to grant as many [static typing](http://en.wikipedia.org/wiki/Type_system#Static_type-checking) guarantees as it can. eg. x = x + y; is checked to ensure that:
	* x and y are both integers(+ operates only on ints in minijava)
	* The left hand side of the assignment, x, has the same type as the expression on the right side. 
3.	Variables are checked to ensure that they are [initialized before use]().  

For a given method f() taking no arguments and returning an integer:
	
```java
	int f(){
		int x;    //declaration
		x=0;      //initialization
		return x; //use
	}
```

should compile, while
	
```java
	int f(){
		int x;    //declaration
		return x; //error, variable x may not have been initialized.
	}
```

should print an [initialization before use error]()

### Bytecode Generation ###

This is where the [magic](CodeGenerator Documentation) happens.  The parse tree is traversed a final time in order to generate [byte code](http://en.wikipedia.org/wiki/Java_bytecode_instruction_listings). 

[//]: # (The ObjectWeb ASM java libraries is used to generate class files.)

[//]: # (Generating bytecode, even with ASM, is akin to [printing assembly](http://jasmin.sourceforge.net/) to a file.)


Build
-----

Building the tool from source requires the [Antlr4 java library](http://www.antlr.org/api/Java/) and the [ASM java library](http://asm.ow2.org/asm50/javadoc/user/org/objectweb/asm/package-summary.html).  

0.	Clone the project from the git [repository](https://github.com/csaroff/MiniJava-Compiler)
1.	Download [Antlr4](http://www.antlr.org/download/antlr-4.4-complete.jar) and [ASM](http://download.forge.ow2.org/asm/asm-5.0.3-bin.zip)
2.	Unzip asm-5.0.3-bin.zip and add asm-5.0.3/lib/all/asm-all-5.03.jar and the antlr jar to your path.  
3.	Generate the lexer and parser by feeding Antlr4 the [minijava grammar](https://github.com/csaroff/MiniJava-Compiler/blob/master/Minijava.g4).

	`java -jar ~/path/to/antlr-4.4-complete.jar -visitor Minijava.g4`

4.	compile with the java 1.8 compiler

	`javac *.java`

And you're done.  If you want to package it as a jar file:

	jar cf minijavac.jar *.class