grilla99 / babycino-compiler Goto Github PK

Babycino v0.3
=============

This is a minimal compiler for MiniJava, a subset of Java used in the book
"Modern Compiler Implementation in Java, Second Edition" by Andrew Appel and
Jens Palsberg. See here for more information about MiniJava:

http://www.cambridge.org/resources/052182060X/MCIIJ2e/

The compiler is written in Java, using the parser generator ANTLR 4. It was
originally written to support the module CS2CO16: Compilers taught at the
University of Reading.

For your convenience, ANTLR 4 and a script to run it are bundled in the
archive. There is also a script to run the "grun" grammar testing tool,
which produces images of parse trees. Note that you must build the compiler
before you can use grun.

Linux Users
-----------

Open a command prompt, navigate to the directory containing this README.txt,
then compile the compiler using the script build.sh:

$ ./build.sh

This runs ANTLR to generate the MiniJava parser, then runs the Java compiler
on the Babycino source code and the parser generated by ANTLR.

To compile a program, use the script babycino.sh. For example:

$ ./babycino.sh progs/appel/Factorial.java factorial.c

This runs Babycino, which generates C code as output. To run the C program,
you need to compile it with a C compiler. For example:

$ gcc factorial.c -o factorial.o
$ ./factorial.o 
3628800

(The C compiler gcc is installed on most Linux systems, but you can use a
different C compiler if you prefer.)

To view a parse tree of a program, use grun. For example:

$ ./grun.sh babycino.MiniJava goal -gui progs/appel/Factorial.java

Windows Users
-------------

Open a command prompt, navigate to the directory containing this README.txt,
then compile the compiler using the script build.bat:

> build

This runs ANTLR to generate the MiniJava parser, then runs the Java compiler
on the Babycino source code and the parser generated by ANTLR.

To compile a program, use the script babycino.bat. For example:

> babycino progs\appel\Factorial.java factorial.c

This runs Babycino, which generates C code as output. To run the C program,
you need to compile it with a C compiler. For example:

> tcc factorial.c -o factorial.exe
> factorial.exe
3628800

(The C compiler tcc is included in the distribution, but you can use a
different C compiler if you prefer.)

To view a parse tree of a program, use grun. For example:

$ grun.sh babycino.MiniJava goal -gui progs\appel\Factorial.java

Other Scripts
-------------

The cleanup script deletes the files generated by ANTLR and .class files
created during compilation.

The test script runs Babycino on Factorial.java, compiles the C output to an
executable, runs the executable, and checks the result is correct. This
shows that some basic features of the compiler are working, but not much
else.

The test-my-archive script takes a .zip or .tar.gz archive of the Babycino
source code, extracts it to a temporary directory, compiles it and runs the
test script. This is useful for checking an archive before releasing it.

Using an IDE
------------

Using an IDE to modify the compiler is complicated, as without careful
setup, the IDE will not know to run ANTLR after you change the grammar. It
will generally be simpler to use a good text editor. Notepad++ is a popular
choice for Windows users.

Bugs
----

Please report any bugs you find. Examples of bugs are crashes (for example,
unhandled null-pointer exceptions) or differences in the behaviour of a
MiniJava program when compiled with Babycino, as compared with the official
Java compiler.

As Babycino maps Java ints onto C ints, some aspects of integer arithmetic
may not match the Java specification exactly. This is intentional.

Licensing
---------

Babycino is distributed under the MIT License.

The sample programs in progs/appel/ are from the aforementioned textbook,
"Modern Compiler Implementation in Java, Second Edition". They remain the
property of the original authors.

The contents of contrib/antlr/ are from the ANTLR, which is distributed
under the BSD License.

The contents of contrib/tcc/ are from TCC, which is distributed under the
GNU Lesser General Public License.

The contents of contrib/infozip/ are from Info-ZIP, which is distributed
under a BSD-like licence.

Changelog
---------

* Version 0.3: Various minor improvements for 2019-20 academic year.
  - Grammar: Correct Java precedence observed.
  - TACGenerator: Fixed bug that occurred when generating a label in main().
  - General: Explicit @Override used for classes that override Java
    visitors/listeners. Stopped using deprecated ANTLR FileStream API.
  - Build: ANTLR libraries bundled to avoid editing classpaths. TCC bundled
    for Windows users with no C compiler. Build scripts use these. Windows
    build/compile scripts added. Zip/unzip binaries added.
  - Readme: Updated to reflect the above changes.

* Version 0.2: Peephole optimiser and dead/redundant code removal added.
  - Optimisation: TACBlockOptimiser.java, TACDeadCodeOptimiser.java and
    TACFlowAnalysis.java added.
  - TAC: NOP (no operation) added to TACOp.java and TACOpType.java.
  - General: Babycino.java tidied up.
  - Readme: Note about ANTLR and -package on Windows added.
  - Build: test-my-archive.sh added to help people check their archives
    compile OK.

* Version 0.1: Initial release. All of MiniJava supported.