README update

Update dependencies, performance details, explain the rationale for
creating pp2cc.

1 files changed, 31 insertions, 11 deletions

diff --git a/README b/README
index 8f7416a..f92bcdf 100644
--- a/README
+++ b/README
@@ -1,12 +1,22 @@
-pp2cc is a C compiler for the PP2 Practicum Processor. It generates assembly
-from C code. Currently, pp2cc is licensed under a proprietary license, but
-this may change in the future.
+pp2cc
+=====
+pp2cc is a C compiler for the PP2 Practicum Processor. This processor (board)
+is created by dr.ir. Rob Hoogerwoord from the University of Technology in
+Eindhoven (TU/e). The resulting assembly can be compiled to machine code using
+Assembler.jar
 
-Dependencies:
+This software was written for the Design Based Learning project "Embedded
+Systems" in 2011 Q2. The assignment required assembly which could be written by
+hand. Xander Houtman thought of dropping that idea and using a C compiler
+instead. Since his string-parsing approach did not work very well, I (Peter Wu)
+looked for a parser library and found pycparser.
 
-- Python - http://python.org/download/
-- pycparser - http://code.google.com/p/pycparser/
-- PLY (Python Lex-Yacc) - http://www.dabeaz.com/ply/
+Dependencies (tested versions in parentheses:
+
+- Python (3.3.3, 2.7.6 recommended) - http://python.org/download/
+- pycparser (v2.10, v2.05 recommended) - https://github.com/eliben/pycparser
+- PLY (Python Lex-Yacc; 3.4) - http://www.dabeaz.com/ply/ (bundled with recent
+  pycparser)
 
 Recommended:
 - cpp - a C preprocessor
@@ -14,10 +24,20 @@ Recommended:
 Python is often installed by default on Linux distributions. For Windows, you
 probably need to run the installer from the above link. Extract the pycparser
 ZIP file (see link above) and copy the pycparser subdirectory to the directory
-containing pp2cc.py. The same goes for PLY: download the tar.gz file and copy
-the ply/ directory into the directory containing pp2cc. pp2cc is a console
-program, you need to open a terminal (or cmd on Windows) to see compiler
-messages.
+containing pp2cc.py. pp2cc is a console program, you need to open a terminal
+(or cmd on Windows) to see compiler messages.
+
+Originally written for Python 2, pycparser v2.05 and external PLY. Meanwhile,
+the same code has worse performance (21 C files, 618 lines in total, 3 trials)
+in newer versions of the dependencies:
+
+- python 3.3.3, pycparser v2.09.1 (and v2.10), bundled PLY: 26 seconds
+- python 2.7.6, pycparser v2.09.1 (and v2.10), bundled PLY: 20 seconds
+- python 3.3.3, pycparser v2.05, PLY 3.4 (external): less than a second
+- python 2.7.6, pycparser v2.05, PLY 3.4 (external): less than a second
+
+Since the bundled version equals the external version (3.4), pycparser seems to
+have some issues with YACC (well, that shows up in profiling).
 
 The cpp program is installed on most Linux distributions. If not, install a
 conforming cpp, say gcc (GNU C Compiler). On Windows, you might want to