CS355 Compiler Project - Roger Gee and Ethan Rutherford - Fall 2014

Roger Gee <[email protected]>
Ethan Rutherford <[email protected]>
--------------------------------------------------------------------------------
This project implements a compiler for the simple programming language
Ramsey designed at Abilene Christian University by the Fall 2014 CS 355 Compiler
Construction class.

This compiler works hand-in-hand with GCC tools to build a native binary
executable file by linking the assembled Ramsey code with assembled C code.
The C code acts as a driver to run the Ramsey code, handling any input and
output operations.

The specification for the Ramsey language is documented in the file
'lang-spec.txt'. This repository also contains numerous sample Ramsey programs.

This compiler compiles Ramsey code down to x86 GAS (GNU Assembler)
instructions; you will need to have GCC installed (MinGW on MS Windows) on
your system in order for the Ramsey compiler to build executable binaries.
Make sure that the GCC toolchain is in your PATH environment variable. When
you invoke the Ramsey compiler, the process will create a pipeline similar to:
    $ ramsey | gcc -m32 -O0 -xassembler - -xc driver.c
--------------------------------------------------------------------------------
Building the project:

The project

The project requires a C++ compiler with full C++-11 support. The makefile
included with the project is (by default) used to build binaries for GNU/Linux.
A Windows batch file has been included to make binaries for MS Windows. For
Apple OS X systems, the makefile should work nicely however the macro
'RAMSEY_APPLE' needs to be defined. Source files that include the name 'posix'
employ POSIX APIs for operating system functionality whereas those that include
the name 'win32' employ the Windows API.
--------------------------------------------------------------------------------
Building the test module:

To compile the project with its testing module, run 'make' with the 'test' rule:
    $ make test

This should generate a single executable that links together the compiler code
and a test module that will display the intermediate compilation stages.

Current operations performed by test module:
    - print out lexical tokens and (if necessary) their source strings
    - print out status of source code parse (passed or failed with message)
    - print out the abstract syntax tree
    - print out status of semantic analysis (passed or failed with message)
    - print out the assembly code generated from the abstract syntax tree

To run the test module, pass a file name to the test program on its
command-line:
    $ ./ramsey-test source.ram
--------------------------------------------------------------------------------
Building the actual compiler:

To compile the compiler, run either the 'all' or 'debug' rules. The standard
make 'all' rule will build the production binary executable file whereas the
'debug' rule will build the testing binary with debug information:
    $ make          # build production binary
    $ make debug    # build debug binary

You can now run the compiler like so:
    $ ./ramsey prog.ram prog-driver.c

The above command will create a binary file called 'prog' that contains
assembled code from both 'prog.ram' and 'prog-driver.c'.
--------------------------------------------------------------------------------
Building on MS Windows:

Included in this repository is a 'build.bat' script to build the project for
MS Windows. You can give it one of several options:
    > build         ::this generates a production build
    > build debug   ::this generates build with debug symbols
    > build test    ::this generates a build using the test module

This script defines the 'RAMSEY_WIN32' macro which targets the application for
MS Windows.
--------------------------------------------------------------------------------