llvm-hs - Haskell bindings for LLVM

This project aims to provide a relatively complete set of bindings for the LLVM API. If you find that anything is missing please open an issue! We generally try to stay close to the LLVM C++-API so you can consult the LLVM documentation and reuse existing resources.

Getting started

If you’ve worked with LLVM before, take a look at the examples in the llvm-hs-examples repo. If not, you can find a translation of the official LLVM tutorial at https://github.com/llvm-hs/llvm-hs-kaleidoscope. There is also a blog series on writing a C compiler with the library. In general, we try to stay very close to the API and AST provided by LLVM itself, so the LLVM language reference is also very useful.

LLVM API Interface

llvm-hs provides an LLVM binding at (roughly) the same level of abstraction as the official LLVM C API. Because of this, anything you might do with the LLVM C API, you should expect to be able to do with llvm-hs. In addition, some things which are not handled in the LLVM C API are supported. For example, the LLVM C API does not provide any support for working with AttributeSet and AttributeList types, but llvm-hs does.

However, the binding to LLVM is only half the story: a lot of advanced pure-Haskell functionality is built on top of this basic interface in the llvm-hs-pure module, most notably the monadic IRBuilder and ModuleBuilder interfaces which greatly simplify the task of generating LLVM code from a higher level abstract syntax. The llvm-hs-examples project contains example usage. These high level interfaces are ideal for implementing the LLVM backend for your code generation project. A good example is Google's Dex research language.

LLVM API Coverage and Philosophy

The llvm-hs FFI layer in LLVM/Internal/FFI extends the upstream LLVM C API adding missing functionality which upstream has not yet exposed from the C++ API. We also provide some improved implementations of buggy or otherwise problematic functions in the LLVM C API. As the LLVM C API becomes more complete, we retire our extensions and directly wrap the newly added C API functions, ensuring our FFI layer is as small as possible.

If you find you need to use some LLVM functionality which is available via the C++ API but not via the C API or in llvm-hs, please open an issue and include links to the relevant entities in the LLVM doxygen-generated documentation.

In general, if it is possible to implement something in Haskell using the LLVM C API primitives, that is preferable to implementing things in the FFI layer and merely exposing them to Haskell as wrapped C or C++ functions.

Contributing

We love all kinds of contributions so please feel free to open issues for missing LLVM features, report & fix bugs or report API inconveniences.

Versioning

Trying to represent the version of LLVM in the version number but also allowing for version bumps in the bindings themselves while respecting the PVP can be tricky. Luckily LLVM switched to a new versioning scheme of major.0.patch starting from version 4.0. This means that we can use the last two components for these bindings while the first component indicates the version of LLVM. A special case are the versions 3.major.minor that represent bindings to LLVM 3.9. Bindings to earlier versions are not provided.

How is this related to llvm-general?

This project is a fork of the venerable llvm-general that aims to improve the public release story, and better provide the interfaces needed for any Haskell project looking to leverage LLVM. Contributions are encouraged.