| blob | 9af591f0c9e926fd0869af5e47b8d871c8b2d0f7 |
1 The Voodoo Compiler
4 Introduction
5 ============
7 The Voodoo compiler is a compiler for the Voodoo programming language.
8 The Voodoo programming language is designed to be a thin abstraction
9 layer over the CPU's native instruction set. It provides functionality
10 to read and write memory, perform arithmetic, define and call
11 functions, and not much more. In particular, Voodoo has no concept of
12 types, let alone type safety. Voodoo is as dangerous as it is
13 powerful. The Voodoo programming language is described in more detail
14 in doc/language.html.
17 Building and Installation
18 =========================
20 Short summary:
22 $ ./configure
23 $ make
24 $ make install
26 The Voodoo compiler can be built by issuing the commands
27 "./configure" followed by "make" from the top-level directory.
29 It is possible to specify a location to install to using the --prefix
30 parameter to configure. By default, the Voodoo compiler is installed to
31 /usr/local. To install to /usr instead, use
33 $ ./configure --prefix /usr
35 The Voodoo compiler can be installed using "make install" from the
36 top-level directory.
39 Usage
40 =====
42 There are two ways to use the Voodoo compiler: as a run-time code
43 generator, or using the stand-alone compiler.
45 Run-Time Code Generation
46 ------------------------
48 To use the Voodoo compiler as a run-time code generator, require
49 'voodoo/code_generator' and instantiate a code generator using
50 Voodoo::CodeGenerator.get_generator, passing :architecture and
51 :format parameters. E.g.
53 require 'voodoo/code_generator'
55 generator = Voodoo::CodeGenerator.get_generator :architecture => :i386,
56 :format => :elf
58 Code and data can be sent to the generator using the methods add_code,
59 add_data, and add_function. Labels can be added using add_code_label,
60 add_data_label, and add_function_label. Imports and exports can be
61 declared using the methods import and export. Section selection is done
62 using the section method. The following is an example of the generation of
63 a simple program:
65 generator.section :data
66 generator.add_data_label :msg
67 generator.add_data [:string, "Hello, world!\\x00"]
69 generator.section :code
70 generator.import :puts
71 generator.export :main
72 generator.add_function_label :main
73 generator.add_function [:argc, :argv],
74 [:call, :puts, :msg],
75 [:return, 0]
77 Finally, output from the generator can be written to a file using the
78 write method. For example:
80 File.open('example.o', 'w') do |file|
81 generator.write file
82 end
84 Using voodooc
85 -------------
87 The program voodooc is a compiler that can be used to compile source
88 code written in Voodoo to object files or assembly code. The compiler
89 requires the name of the source file to be compiled as an argument.
90 Additionally, the output file name can be specified using the "-o"
91 option, and the output format and architecture may be specified using
92 the "-f" and "--architecture" options. Some examples:
94 $ voodooc -o example.o example.voo
96 $ voodooc -f nasm -o example.asm example.voo
98 $ voodooc --architecture i386 -f elf -o example.o example.voo
100 Creating Executables
101 --------------------
103 The Voodoo compiler produces object files (or assembly code that can
104 be turned into object files). To create executable programs from
105 object files, the object files must be linked. The linking steps
106 to be performed depend on the operating system and the libraries
107 to be linked with.
109 The following example uses the C compiler to link an object file
110 example.o with the C library to produce an executable named example:
112 $ cc example.o -o example
114 This is not the only way to get a working executable. Voodoo programs
115 can use other libraries than the C library, or even no library at
116 all. Linking with the C library is just used as a convenient way to
117 get a working puts function.