petard

a js llvm library

    For 'tis the sport to have the enginer
    Hoist with his own petar'...

                - Hamlet, Shakespeare

[introduction][90]
[dependencies][91]
[getting started][92]
[documentation][93]
- [petard types][15]
  - [Type][10]
  - [Value][11]
  - [Builder][12]
  - [FunctionBuilder][13]
  - [SwitchBuilder][18]
  - [ChooseBuilder][19]
  - [CodeUnit][14]
- [helpers][16]
  - [type dict][17]
[more information][94]

introduction

Frustrated with the state of JS support for LLVM, I built another library. Rather than trying to be generic bindings to libLLVM, petard tries to make the most common case easy: generating fresh IR. You don't have total control over the LLVM machinery and there aren't really facilities for working with IR that already exists (so you can't write passes), but if those limitations aren't a problem petard makes dealing with LLVM much simpler.

This software is under active development. The README should reflect current functionality, but don't be surprised if something you think should work causes your computer to segfault. petard aims to catch these things and throw JavaScript errors, but we don't have very good coverage yet. Please do submit a ticket or pull request if there's a type of programmer error that could be caught earlier and an error thrown.

one more warning: it is currently VERY leaky. don't use in any program that will be running very long.

dependencies

a recent version of node
nan version 2.1
llvm version 3.9

getting started

First you need to install LLVM version 3.9 on your system, including the dev libs. Look to the Travis build config for details.

when you're building petard you will need to set the environment variable LLVM_CONFIG to be the llvm-config you've installed. For example, if you're on Ubuntu where it's isntalled as llvm-config-3.9, you'll enter:

> LLVM_CONFIG=llvm-config-3.9 npm run build

> LLVM_CONFIG=llvm-config-3.9 npm install petard

Once you've got it built successfully, try this:

llvm = require 'petard'

{i8, i32, pointerTo} = llvm.type

hello = llvm.CodeUnit "hello"

main = hello.makeFunction "main", i32
puts = hello.declareFunction "puts", i32, pointerTo i8

text = hello.constant "Hello, world!\n"

message = main.loadConstant text
main.callFunction puts, message

main.return 0

hello.writeBitcodeToFile "hello.bc"

Then use opt and clang as usual with the LLVM IR bitcode file. Look at the [example][21] folder for more examples.

Alternatively, you can JIT compile and call the function from JavaScript.

hi = hello.makeFunction "hi", i32, pointerTo i8

prefix = hello.constant "Hello, "

hi.callFunction puts, hi.loadConstant prefix
hi.callFunction puts, hi.parameter 0

hi.return 0

greet = hi.jitCompile()

greet "Bill"
greet "Janice"
greet "Bart"

documentation

The underlying C++ API exposes the basics of LLVM IR construction, and the node wrapper adds some higher-level functionality on top of that. In the listing the methods in JavaScript are marked with a (js).

[petard types][15]
- [Type][10]
- [Value][11]
- [Builder][12]
- [FunctionBuilder][13]
- [SwitchBuilder][18]
- [CodeUnit][14]
[helpers][16]
- [type dict][17]

petard types

Type

Represents an LLVM type. You'll see these most commonly when you get them from petard.type and pass them when constructing functions and values. The only thing you can do to a type is get its name as a string.

String type.toString()

Returns the type as a string.

Value

Represents an LLVM value, or if you look at it another way, represents an abstract expression. You'll get these and pass them in to many of the builder methods. The only thing you can do to a value is get its type.

[Type][10] value.type

A property containing the type of the value.

Builder

Something that can construct LLVM IR. It represents a particular part of a function (an LLVM block) as well as a cursor within that block where instructions will be placed. Calls to builder methods construct LLVM IR and take and return values and other builders.

return([Number|[Value][11] value])

Return from the function. If a value is provided, it is the return value of the function. You must ensure that the value passed is of the same type as the return type of the function.

[Value][11] parameter(Number index)

Reference function parameter index.

[Value][11] getElementPointer([Value][11] base, Number|[Value][11] indexList...)

Perform pointer math on the aggregate type pointer to produce a new pointer to the given structure member. For details, see the [GetElementPointer FAQ][2].

[Value][11] extractElement([Value][11] vec, Number|[Value][11] index)

Extract the element at the specified index from the vector.

[Value][11] insertElement([Value][11] vec, [Value][11] value, Number|[Value][11] index)

Insert the value as the element at the specified index from the vector.

[Value][11] loadConstant([Value][11] constant)

Load a constant value. Currently the only usage is to load a string constant, see the first example.

[Value][11] callFunction([FunctionBuilder][13]|[FunctionValue][20] fn, [[Value][11] params...])

Call the given internal or external function, passing in the parameter values.

[Value][11] alloca([Type][10] type, [Number|[Value][11] arraySize])

Allocate space the size of type on the stack. If an arraySize is provided, instead allocate that much space times the arraySize. Returns a pointer value to the space.

[Value][11] load([Value][11] pointer)

Load a value from the memory pointed to by pointer.

store([Value][11] value, [Value][11] pointer)

Store the value in the memory pointed to by pointer.

[Value][11] add([Value][11] left, [Value][11] right)

Add the values. Works on integer and float values.

[Value][11] sub([Value][11] left, [Value][11] right)

Subtract the right value from the left. For integers and floats.

[Value][11] mul([Value][11] left, [Value][11] right)

Multiply the values. They can be integers or floats.

[Value][11] udiv([Value][11] left, [Value][11] right)

Unsigned integer divide the left value by the right.

[Value][11] sdiv([Value][11] left, [Value][11] right)

Signed integer divide the left value by the right.

[Value][11] fdiv([Value][11] left, [Value][11] right)

Floating point divide the left value by the right.

[Value][11] urem([Value][11] left, [Value][11] right)

The remainder when the left value is unsigned integer divided by the right.

[Value][11] srem([Value][11] left, [Value][11] right)

The remainder when the left value is signed integer divided by the right.

[Value][11] frem([Value][11] left, [Value][11] right)

The remainder when the left value is floating point divided by the right.

[Value][11] and([Value][11] left, [Value][11] right)

Bitwise and the values.

[Value][11] or([Value][11] left, [Value][11] right)

Bitwise or the values.

[Value][11] xor([Value][11] left, [Value][11] right)

Bitwise xor the values.

[Value][11] shl([Value][11] left, [Value][11] right)

Shift the left value left by the right value number of bits.

[Value][11] lshr([Value][11] left, [Value][11] right)

Shift the left value right logically (sign-ignoring) by the right value number of bits.

[Value][11] ashr([Value][11] left, [Value][11] right)

Shift the left value right arithmetically (sign-preserving) by the right value number of bits.

[Value][11] equal([Value][11] left, [Value][11] right)

Compare the values for equality.

[Value][11] notEqual([Value][11] left, [Value][11] right)

Compare the values for inequality.

[Value][11] uGreaterThan([Value][11] left, [Value][11] right)

Unsigned greater than comparison.

[Value][11] uAtLeast([Value][11] left, [Value][11] right)

Unsigned greater than or equal to comparison.

[Value][11] uLessThan([Value][11] left, [Value][11] right)

Unsigned less than comparison.

[Value][11] uAtMost([Value][11] left, [Value][11] right)

Unsigned less than or equal to comparison.

[Value][11] sGreaterThan([Value][11] left, [Value][11] right)

Signed greater than comparison.

[Value][11] sAtLeast([Value][11] left, [Value][11] right)

Signed greater than or equal to comparison.

[Value][11] sLessThan([Value][11] left, [Value][11] right)

Signed less than comparison.

[Value][11] sAtMost([Value][11] left, [Value][11] right)

Signed less than or equal to comparison.

[Value][11] foEqual([Value][11] left, [Value][11] right)

Float value ordered equality comparison.

[Value][11] foNotEqual([Value][11] left, [Value][11] right)

Float value ordered inequality comparison.

[Value][11] foGreaterThan([Value][11] left, [Value][11] right)

Float value ordered greater than comparison.

[Value][11] foAtLeast([Value][11] left, [Value][11] right)

Float value ordered greater than or equal to comparison.

[Value][11] foLessThan([Value][11] left, [Value][11] right)

Float value ordered less than comparison.

[Value][11] foAtMost([Value][11] left, [Value][11] right)

Float value ordered less than or equal to comparison.

[Value][11] fuEqual([Value][11] left, [Value][11] right)

Float value unordered equality comparison.

[Value][11] fuNotEqual([Value][11] left, [Value][11] right)

Float value unordered inequality comparison.

[Value][11] fuGreaterThan([Value][11] left, [Value][11] right)

Float value unordered greater than comparison.

Petard

Install / Use

README