| blob | 2c3d3cf5df215ea9335ffdef7746104ec8e029ff |
1 The Voodoo Compiler
4 Introduction
5 ============
7 The Voodoo compiler is a compiler for the Voodoo programming language.
8 Voodoo is a programming language designed to be a thin abstraction
9 layer over CPUs' native instruction sets and operating systems'
10 calling conventions. Operations provided by Voodoo closely correspond
11 to those of common CPU instruction sets, allowing programs to be
12 expressed with a minimum of overhead. At the same time, Voodoo is not
13 tied to a specific instruction set, and support for new CPUs and
14 operating systems can easily be added. The Voodoo programming
15 language is described in more detail in doc/language.html.
18 Building and Installation
19 =========================
21 Short summary:
23 $ ./configure
24 $ make
25 $ make install
27 The Voodoo compiler can be built by issuing the commands
28 "./configure" followed by "make" from the top-level directory.
30 It is possible to specify a location to install to using the --prefix
31 parameter to configure. By default, the Voodoo compiler is installed to
32 /usr/local. To install to /usr instead, use
34 $ ./configure --prefix /usr
36 The Voodoo compiler can be installed using "make install" from the
37 top-level directory.
39 As an alternative to running "make install", when RubyGems is installed,
40 a gem can be created by running "make gem", and installed using
41 "gem install voodoo*.gem".
44 Usage
45 =====
47 There are two ways to use the Voodoo compiler: as a run-time code
48 generator, or using the stand-alone compiler.
50 Run-Time Code Generation
51 ------------------------
53 To use the Voodoo compiler as a run-time code generator, require
54 'voodoo/code_generator' and instantiate a code generator using
55 Voodoo::CodeGenerator.get_generator, passing :architecture and
56 :format parameters. E.g.
58 require 'voodoo/code_generator'
60 generator = Voodoo::CodeGenerator.get_generator :architecture => :i386,
61 :format => :elf
63 The :architecture and :format parameters can be omitted if the defaults
64 determined by ./configure are acceptable. Typically, the default is
65 to create an object file for architecture that the compiler is being
66 run on.
68 Code and data can be sent to the generator using the methods add, and
69 add_function. The following is an example of the generation of a
70 simple program:
72 generator.add :data, [:label, :msg], [:string, "Hello, world!\x00"]
74 generator.add :functions, [:import, :puts], [:export, :main], [:label, :main]
75 generator.add_function [:argc, :argv],
76 [:call, :puts, :msg],
77 [:return, 0]
79 Finally, output from the generator can be written to a file using the
80 write method. For example:
82 File.open('example.o', 'w') do |file|
83 generator.write file
84 end
86 Using voodooc
87 -------------
89 The program voodooc is a compiler that can be used to compile source
90 code written in Voodoo to object files or assembly code. The compiler
91 requires the name of the source file to be compiled as an argument.
92 Additionally, the output file name can be specified using the "-o"
93 option, and the output format and architecture may be specified using
94 the "-f" and "-a" options. Some examples:
96 $ voodooc -o example.o example.voo
98 $ voodooc -f nasm -o example.asm example.voo
100 $ voodooc --architecture i386 -f elf -o example.o example.voo
102 Specifying "-" as the input file name causes voodooc to read
103 Voodoo code to be compiled from standard input.
105 Creating Executables
106 --------------------
108 The Voodoo compiler produces object files (or assembly code that can
109 be turned into object files). To create executable programs from
110 object files, the object files must be linked. The linking steps
111 to be performed depend on the operating system and the libraries
112 to be linked with.
114 The following example uses the C compiler to link an object file
115 example.o with the C library to produce an executable named example:
117 $ cc example.o -o example
119 This is not the only way to get a working executable. Voodoo programs
120 can use other libraries than the C library, or even no library at
121 all. Linking with the C library is just used as a convenient way to
122 get a working puts function.