Added PIRC Development docs

docs/TODO.mdown

@@ -0,0 +1,16 @@
+PIRC Development Tasks
+======================
+
+Shouldn't-be-too-hard tasks
+---------------------------
+
+* write tests for the generated output.
+
+Hardcore hacking tasks
+----------------------
+
+* Fix parser to "calculate" the right signature for ops such as: `$P0 = new ['Integer']`
+
+Currently, the argument is encoded as `_ksc`, for key, string-constant.
+
+* Convert all C strings in PIRC into `STRINGs`. All identifiers and strings that are scanned should be stored as `STRING` objects, not C strings.

docs/current_status.mdown

@@ -0,0 +1,4 @@
+PIRC Status
+===========
+
+PIRC is not complete yet. All stages are implemented (lexer, parser, bytecode generator), but all of them need some additional work to complete them. See the section below for the specific items that need to be fixed. Once these are fixed, PIRC will be done about 98%.

docs/general.mdown

@@ -0,0 +1,49 @@
+PIRC Introduction
+=================
+
+PIRC is a fresh implementation of the PIR language. It is being developed as a replacement for the current PIR compiler, IMCC. Somewhere in the future, we all hope to be able to finish it. However, some help is needed. Most of the tricky parts have been done for you, such as implement all sorts of weird features of the PIR language.
+
+The basic workflow of PIRC is as follows. The lexer and parser are implemented with Flex and Bison specifications. During the parsing phase, a data structure is built that represents the input. To stick with compiler jargon, let's call this the Abstract Syntax Tree (AST). After the parse, this AST is traversed and for each instruction the appropriate bytecode is emitted. Registers are allocated by the built-in vanilla register allocator. This means that for the following code:
+
+	.sub main
+	  $S12 = "Hi there"
+	  print $S12
+	  $I44 = 42
+	  print $I44
+	.end
+
+`$S12` and `$I44` will be mapped to the registers `S0` and `I0` respectively (yes, you guessed it, it starts allocating from 0). As you would expect, the vanilla register allocator is pretty stupid, but the generated bytecode is not too bad, really. If you want to optimize the register usage (which saves runtime memory), you can activate the register optimizer. The register optimizer is based on a Linear Scan Register allocator. The original algorithm, as described in [this paper](http://www.google.ie/url?sa=t&source=web&ct=res&cd=1&url=http%3A%2F%2Fwww.cs.ucla.edu%2F~palsberg%2Fcourse%2Fcs132%2Flinearscan.pdf&ei=w9F5SvzVDpOqsAa_7tyeBQ&usg=AFQjCNETIxGGy87F9GzLawd4euXEaldcnQ&sig2=Hd7nnjdQrgnOqix-8sx92g), assumes a fixed number of available registers. Since Parrot has a variable number of registers available per subroutine, the algorithm has been changed here and there. See the file [/src/pirregalloc.c](https://github.com/parrot/pirc/blob/master/src/pirregalloc.c) for the implementation.
+
+PIRC vs IMCC
+============
+
+While PIRC is an implementation of the PIR language which is specified in PDD19, there are some subtle differences with the current implementation, IMCC. In case you were wondering, IMCC stands for IMC Compiler, with IMC being the old name of the PIR language, standing for Intermediate Machine Code. The name was changed a long time ago.
+
+* "nested" heredocs, can be handled by PIRC, not by IMCC. Yes, it was very painful to implement which is why IMCC doesn't.
+* comments or whitespace in the parameter lists are accepted by PIRC, but not by IMCC. It sounds like an easy fix, but it isn't. Hence, PIRC!
+* reentrant: PIRC is, IMCC is not.
+* checks for improper use syntactic sugar with OUT arguments, such as `$S0 = print`. PIRC checks for this, IMCC doesn't. Again, it sounds (and looks) like an easy fix, but it isn't.
+* PIRC handles macros in the lexer and parser; the syntax to define macros is defined in the parser. IMCC on the other hand implements macro's completely in the lexer.
+
+Building and running PIRC
+=========================
+
+PIRC is located in compilers/pirc. In order to compile, do the following:
+
+	cd compilers/pirc
+	make
+	make test
+
+At this point (August 5, 2009) some tests are failing, so don't be alarmed if you see them failing.
+
+In order to run PIRC:
+
+	./pirc -h
+	./pirc -b test.pir # will generate a file a.pbc
+
+Enjoy!
+
+PIRC Data Flow
+==============
+
+The data flow of PIRC is as follows. First, the [heredoc preprocessor](https://github.com/parrot/pirc/blob/master/src/hdocprep.l) takes the PIR file and flattens all heredoc strings. The output is written to a temporary file, which is then parsed by the [Flex based lexer](https://github.com/parrot/pirc/blob/master/src/pir.l) and the [Bison based parser](https://github.com/parrot/pirc/blob/master/src/pir.y). The parser create an Abstract Syntax Tree (AST); the AST nodes for that are defined in [/src/pircompunit.c](https://github.com/parrot/pirc/blob/master/src/pircompunit.c). If the parse was successful, control is passed on to the [/src/piremit.c](https://github.com/parrot/pirc/blob/master/src/piremit.c) module, which traverses the AST. During the traversal, bytecode is generated through the [/src/bcgen.c](https://github.com/parrot/pirc/blob/master/src/bcgen.c) module. The output is written to a file named a.pbc; the name of the output file can be overridden with the `-o[wi` option.