Voodoo Compiler

Introduction

The Voodoo compiler is an implementation of the Voodoo programming language. The Voodoo programming language is a low-level programming language, abstracting over the platform's instruction set and calling conventions, but otherwise leaving the programmer free to do anything at all. The Voodoo compiler is written in Ruby and generates code for i386-compatible, AMD64, and MIPS CPUs. Support for additional target CPUs is planned for the future.

The Voodoo Programming Language

The Voodoo programming language page provides a detailed description of the Voodoo programming language.

Download

The Voodoo compiler is open source and freely available under the terms of the GNU Lesser General Public License, version 2.1. There are two main ways to obtain Voodoo: releases and the development branch.

The development branch is where development occurs, and has the latest features, bug fixes, and new bugs. It is recommended for developers who wish to contribute to Voodoo or develop their own software based on it.

Releases are snapshots from the development branch that have been deemed ready for public consumption. They have received some amount of testing and the included documentation matches the included software. If you want to use Voodoo, but do not want to modify the compiler itself, you should probably get one of the releases.

Releases

The latest release of the Voodoo compiler is version 0.6.2, available here: voodoo-0.6.2.tar.bz2 (39 KB). This release fixes bugs in the implementations of set-word for i386 and AMD64 and adds tests for the cases that previously did not work correctly.

The previous release, 0.6.1, introduced the following features:

• In addition to i386 and AMD64, the compiler now supports MIPS. Two new target platforms have been added: mips (big-endian) and mipsel (little-endian). For both platforms, the compiler can generate assembly code for use with the GNU assembler or use the GNU assembler to generate ELF object files containing machine code.
• The platform autodetection code has been moved from configure to the run-time code. This means that the compiler now autodetects the platform it is running on and defaults to generating code for that platform if no target platform is explicitly specified. It is still possible to set a specific platform as the default using configure.
• A new method, output_file_suffix, has been added to the code generator API. It returns the canonical suffix for files generated by the code generator.
• The language description has been updated to reflect the current state of the language. In particular, descriptions of comments, sections, and alignment have been added, and some cases in which the semantics are not strictly defined have been noted.

Development Branch

The latest version of the Voodoo compiler is available via Git from the Voodoo Git repository. It can be checked out with the following command:

git clone git://repo.or.cz/voodoo-lang.git voodoo

Note that this is the development branch of the Voodoo compiler, so it will generally have more features than the releases on this webpage, but be less thoroughly tested.

Installation

The Voodoo compiler can be installed using the common configure, make, make install mantra. This means that the steps to installation are:

1. Obtain the files. You can either download a release, or fetch a current development snapshot using git. If you have downloaded a release tarball, you can extract the files in it using a command like bunzip < voodoo-0.6.2.tar.bz2 | tar xf -.
2. Run configure. Enter the directory where you have stored the files. There is a script there called configure. You can run it using a command like ./configure. The script will check if you have all the required software installed and create a file Makefile.cfg for you. If configure reports that some programs are missing, you should install them first.
3. Run make. The command make is used to perform any steps required to build the compiler. Running make without arguments will perform a default build. Afterwards, you can run make test to run the provided tests, and you can run make rdoc to generate API documentation from the Ruby source code.
4. Run make install. The final step is to run make install to install the software and the documentation. You may have to perform this action as root or using sudo, e.g. sudo make install.

Usage

There are two main ways to use the Voodoo compiler: by running the voodooc program, or by using the Ruby API.

The voodooc program compiles a Voodoo source files. Its usage is described in the voodooc.1 manpage, included in the distribution. The following is an example of how voodooc can be used to create an executable hello from a source file hello.voo:

$ voodooc hello.voo
$ cc hello.o -o hello
$ ./hello
Hello, world!

An implementation of hello.voo can be found in the directory test of the distribution.

The second way to use the Voodoo compiler is by using it from a Ruby program. This can be used, for example, to generate code for the target platform without having to create a .voo file. The following is an example which creates an object file called fact.o, containing a definition of a function fact which computes factorials:

require 'voodoo'

generator = Voodoo::CodeGenerator.get_generator :architecture => :i386,
                                                  :format => :elf

generator.export :fact
generator.add_function_label :fact
generator.add_function [:n],
  [:ifle, [:n, 1],
    # then
    [[:return, 1]],
    # else
    [[:let, :x, :sub, :n, 1],
     [:set, :x, :call, :fact, :x],
     [:return, :mul, :n, :x]]]

File.open('fact.o', 'w') { |outfile| generator.write outfile }

The Voodoo compiler API that is a available to Ruby programs is described in the API documentation.

Test Matrix

The following table given an overview of the platforms the Voodoo compiler has been tested on. For each platform, the table lists the machine architecture, the name of the operating system, the version of the operating system, the latest version of the Voodoo compiler that was tested, and if it worked (passed all testcases).

Architecture	Operating System	OS Version	Voodoo Version	Works?
amd64	Ubuntu	10.04	0.6.2
mipsel	Debian GNU/Linux	5.0	0.6.2
i386	DragonFly BSD	2.4.1	0.6.2