Voodoo Compiler

Voodoo Compiler

Robbert Haarman

2014-01-06


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, ARM, and MIPS CPUs.


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 1.1.3, available here: voodoo-1.1.3.tar.bz2 (66 KB). This is a maintenance release, and contains the following bug fixes and improvements:

  • Compatibility with Ruby 1.8, 1.9 and 2.0, tested with MRI/YARV and Rubinius.
  • Labels that start in underscores now work.
  • Programs that use symbols and then try to export or import them are now rejected.

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

To run the Voodoo compiler, you need to have the following software installed:

  • A Ruby implementation. MRI 1.8 and 1.9 should work. If you use something a different Ruby implementation, please let me know if it worked or not.
  • To produce object files, you will need an assembler for your target architecture.
    • For i386 and AMD64, NASM and YASM are supported
    • For other architectures, the GNU Assembler is supported
  • To produce executables, you will need a linker. If you link with the C library, the easiest way is usually to use the C compiler (cc). GNU ld will work, too, if you pass it the right options. Other linkers have not been tested.

If you have RubyGems installed, the easiest way to install the Voodoo compiler is by running the command gem install voodoo.

If you have the source code of the compiler (see Download), you can install it 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-1.1.3.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

generator.add :functions, [:export, :fact], [: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 Debian GNU/Linux 7.1 1.1.3 yes
i386 Debian GNU/Linux 7.1 1.1.3 yes
i386 DragonFly BSD 2.4.1 1.1.3 yes
mipsel Debian GNU/Linux 5.0 1.1.3 yes
arm Raspbian wheezy 1.1.3 yes