# Description
=============
	A compiler frontend that parses pl0e(pl/0 extended) language, development based on llvm compiler infrastructure.

# How to use
============
	# overview description:
	-----------------------
	1. install llvm 6.0.0
	2. compile the pl0e.cpp (the source code of pl0e compiler frontend)
	3. run compiler frontend
	
	# detailed description:
	-----------------------
	0. This program has been done and tested on linux only, so the platform that it can warrant to run successfuly is linux.
	1. On linux, please download llvm 6.0.0 source codes first, optionally, you can download the clang compiler source co-
	   des provided by llvm, clang can act as your c/c++ compiler, and put it to the "tools/" sub-directory of llvm source,
	   the llvm 6.0.0 and clang can get from here, "http://releases.llvm.org/", then you need to build llvm, there is a
	   tutorial that provide information about build llvm with cmake, you can follow it to build llvm,
	   "http://releases.llvm.org/6.0.0/docs/CMake.html", after you build llvm successfully, then install it to path
	   "/usr/local", do not worry because this is the default directory to install when you follow the tutorial of cmake,
	   then, if your "PATH" environment not include the "bin" sub-directory of "/usr/local" path, please include it using
	   command "PATH=${PATH}:/usr/local/bin" to use tools provided by llvm.
	2. Use c++ compiler that support c++11 to compile file "pl0e.cpp", says that you have "clang++" compiler and this tar-
	   ball is extracted to path "/tmp/llvm-frontend-pl0e/", 
	   then you can run the compilation command "clang++ -g -O3 /tmp/llvm-frontend-pl0e/pl0e.cpp `llvm-config --cxxflags 
	   --ldflags --system-libs --libs all` -rdynamic -o pl0e" to compile it, or if you use g++, then use this command 
	   "g++ -std=c++11 -g /tmp/llvm-frontend-pl0e/pl0e.cpp `llvm-config --cxxflags --ldflags --system-libs --libs all` 
	   -rdynamic -o pl0e" to compile it.
	3. Ok, run it right now, the tarball contains many test programs under the "test/" directory, the function of programs
	   has been commented in files or you can easily read the file name to know about it, for example, the
	   "/tmp/llvm-frontend-pl0e/test/canlendar.pl0e" file, it is the program that can print the calendar of your input year,
	   use command "./pl0e < test/canlendar.pl0e" to run it.
	*. You can also write some pl0e programs by yourself according to the grammar of pl0e, see the "pl0e-grammar.txt" for 
	   details, if you have trouble by read EBNF grammar, you may need learn some knowledgement of it from web, here is the
	   wiki page for it, "https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form".
	*. Hopefully you can have fun with it.
	
# How to use the object file generated by pl0e compiler frontend
================================================================
	# overview description:
	-----------------------
	1. run pl0e frontend
	2. emit object file "output.o"
	3. use command "gcc output.o pl0e-lib.c" to emit executable file
	
	# detailed description:
	-----------------------
	The object file generated by pl0e compiler frontend named "output.o", according to the design of pl0e compiler frontend,
	this design put a "main" function for each pl0e program, so this object file can be treated as a object file of C langu-
	age, but you normally could not to directly compile it by C compiler such as "gcc", because if your pl0e program 
	contains some statement that needs external function, such as input statement(? statement), output statement
	(! statement), then if you run directly "gcc output.o", there often will show you information like 
	"undefined reference to ...", this means some symbols needed by "output.o" can not find, what is happened?
	when you JIT(Just-In-Time compilation, directly run the llvm ir produced by pl0e frontend) your pl0e program in pl0e 
	compiler frontend, that's OK, because frontend contains all the needed function within it, but when you want to run the
	object file outside the frontend, you will need these neccesary functions, these functions already written in an extern-
	al library named "pl0e-lib.c", so if you want to run your object file, compile together with it, for example, you can
	use this command, "gcc output.o pl0e-lib.c".

# Tools/platform used version
=============================
	Linux kernal: 3.10.0-514.el7.x86_64
	Linux distribution: CentOS 7
	LLVM: 6.0.0
	clang++: 6.0.0
	gcc/g++: 4.8.5 20150623 (Red Hat 4.8.5-11) (GCC)

# Program information
=====================
	author: hexiaole
	e-mail: [email protected]
	done-date: 2018.06

# Files hierarchy description
=============================
	. (llvm-frontend-pl0e/)
	|
	+---> dump/
	|	+---> arrar-ast.txt (the AST of pl0e array test program)
	|	|
	|	+---> arrar-ir.txt (the Intermidiate Representation of pl0e array test program)
	|	|
	|	`---> ... (some other pl0e programs LLVM IR(Intermediate Representation) and AST(Abstract Syntax Tree))
	|
	+---> LICENSE (follow the declaration of MIT(Massachusetts Institute of Technology) license)
	|
	+---> pl0e.cpp (pl0e compiler frontend source file, written in C++)
	|
	+---> pl0e-grammar.txt (pl0e grammar in EBNF(Extended Backus–Naur Form) format)	
	|
	+---> pl0e-jit.h (the C++ header file for JIT(Just-In-Time compilation) of pl0e compiler frontend, based on the llvm)
	|
	+---> pl0e-lib.c (the library file needed by generated object file)
	|
	+---> README (this file, introduce some information about the pl0e compiler frontend)
	|
	`---> test/
		+---> calendar.pl0e (the most complicated pl0e test program that print calendar of specified year)
		|
		`... (others pl0e programs that execute different task to test the feature of language, see files about detail)