added README

README

@@ -0,0 +1,60 @@
+sjs
+sami.samhuri@gmail.com
+2009-09-22
+
+A compiler for fun and education.  Written (mostly) in Ruby and based
+on the tutorial "Let's Build a Compiler" by Jack Crenshaw.  I wasn't
+satisfied using an external assembler and outputing assembly text so I
+wrote an x86 assembler in Ruby.  It assembles just the instructions I
+need for this compiler, so it is by no means complete.  32-bit only
+and no prefixes are supported.  It's basically just a handful of
+instructions and mod-rm encoding.  I use the system's linker and have
+no intention of writing my own, don't worry!
+
+The code currently consists of a recursive descent parser that outputs
+x86 code in ELF binaries* on Linux and Mach-O binaries on Darwin.
+Most of the code for outputing executables is Ruby, but ELF support is
+still in C and not published in the repository.  Classes to output
+Mach-O and ELF binaries are found in asm/(elf|macho)writer.rb, but ELF
+support is not implemented yet so binaries only compile and run on OS
+X right now. ELF should come soon as I now have lights in my den. :)
+
+Some major refactoring is needed as the project grew organically and
+in order to keep up with the tutorials I have not yet made radical
+changes.  The asm/ directory holds the assembler but also the MachO
+and ELF code, for now.  The assembler is a from-scratch implementation
+in Ruby. This is my first assembler and first time working with the
+x86 ISA, so it probably isn't great.  It outputs horribly inefficient
+code and there are no optimizations.
+
+Hopefully I can reduce the number of lines by factoring more, but it's
+pretty slim at ~3000 LOC.  About 2100 of those are actual code.  I did
+not write this compiler with the intention of anyone else reading it
+but there are a reasonable about of comments.
+
+
+ Real   Total  Filename
+ Lines  Lines
+ -----  -----  --------
+   87  /  112  build.rb
+  617  /  891  compiler.rb
+   12  /   29  asm/asm.rb
+  569  /  843  asm/binary.rb
+  197  /  319  asm/cstruct.rb
+    4  /    6  asm/elfsymtab.rb
+    4  /    8  asm/elfwriter.rb
+  170  /  374  asm/machofile.rb
+   95  /  163  asm/macho.rb
+   19  /   28  asm/machosym.rb
+   48  /   77  asm/machosymtab.rb
+   19  /   25  asm/machowriter.rb
+   16  /   25  asm/objwriter.rb
+   20  /   31  asm/registers.rb
+   42  /   66  asm/regproxy.rb
+   56  /   89  asm/symtab.rb
+  131  /  183  asm/text.rb
+ 2097  / 3269  total
+
+
+Happy hacking!
+-sjs