lib/voodoo.rb

   1 require 'voodoo/config'
   2 require 'voodoo/code_generator'
   3 require 'voodoo/compiler'
   4 require 'voodoo/parser'
   5
   6 # = Voodoo - Code Generation for Multiple Target Platforms
   7 #
   8 # This module implements a compiler for the {Voodoo programming
   9 # language}[http://inglorion.net/documents/designs/voodoo/], a simple
  10 # programming language designed to be a thin abstraction of the CPU's
  11 # native instruction set.
  12 #
  13 # The compiler consists of three parts:
  14 #
  15 # 1. The parser (Voodoo::Parser), which reads
  16 #    Voodoo[http://inglorion.net/documents/designs/voodoo/] source code and
  17 #    turns it into Ruby[http://www.ruby-lang.org/] objects.
  18 #
  19 # 2. The code generator (a class that implements the methods of
  20 #    Voodoo::CommonCodeGenerator), which provides methods that generate
  21 #    code for the target platform.
  22 #
  23 # 3. The compiler driver (Voodoo::Compiler), which reads from the parser
  24 #    and calls the appropriate methods of the code generator.
  25 #
  26 # Both the parser and the code generators can be used on their own. For
  27 # example, you could use the code generator to generate native code for
  28 # your own programming language without first creating a
  29 # Voodoo[http://inglorion.net/documents/designs/voodoo/] program.
  30 #
  31 # Instead of instantiating a code generator directly, it is recommended
  32 # that you use Voodoo::CodeGenerator.get_generator to obtain a suitable
  33 # code generator for your target platform.
  34 #
  35 # A few examples to clarify the usage of the module:
  36 #
  37 # The following code compiles the source file <tt>test.voo</tt> to an ELF
  38 # object file called <tt>test.o</tt> containing object code for i386:
  39 #
  40 #   require 'voodoo'
  41 #
  42 #   File.open('test.voo') do |infile|
  43 #     parser = Voodoo::Parser.new infile
  44 #     generator = Voodoo::CodeGenerator.get_generator :architecture => :i386,
  45 #                                                     :format => :elf
  46 #     File.open('test.o', 'w') do |outfile|
  47 #       compiler = Voodoo::Compiler.new parser, generator, outfile
  48 #       compiler.compile
  49 #     end
  50 #   end
  51 #
  52 # The following code uses the code generator API to create an object file
  53 # without the need to create a
  54 # Voodoo[http://inglorion.net/documents/designs/voodoo/] program:
  55 #
  56 #   require 'voodoo'
  57 #
  58 #   generator = Voodoo::CodeGenerator.get_generator
  59 #
  60 #   generator.add :functions, [:export, :fact], [:label, :fact]
  61 #   generator.add_function [:n],
  62 #     [:ifle, [:n, 1],
  63 #       # then
  64 #       [[:return, 1]],
  65 #       # else
  66 #       [[:let, :x, :sub, :n, 1],
  67 #        [:set, :x, :call, :fact, :x],
  68 #        [:return, :mul, :n, :x]]]
  69 #
  70 #   File.open('fact.o', 'w') { |outfile| generator.write outfile }
  71 #
  72
  73 module Voodoo
  74 end