llvm-party: General purpose LLVM bindings

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Warnings:

llvm-party is a set of Haskell bindings for LLVM http://llvm.org/. Unlike other current Haskell bindings, it uses an ADT to represent LLVM IR (http://llvm.org/docs/LangRef.html), and so offers two advantages: it handles almost all of the stateful complexities of using the LLVM API to build IR; and it supports moving IR not only from Haskell into LLVM C++ objects, but the other direction - from LLVM C++ into Haskell. This is a fork of llvm-hs, with a major advantage that it's being maintained, for now.


[Skip to Readme]

Properties

Versions 12.1.0, 12.1.0, 12.1.1
Change log CHANGELOG.md
Dependencies array (>=0.4.0.0 && <0.6), attoparsec (>=0.13 && <0.15), base (>=4.9 && <5), bytestring (>=0.10 && <0.12), containers (>=0.4.2.1 && <0.7), exceptions (>=0.8 && <0.11), fail (<4.10), mtl (>=2.1.3 && <2.3), template-haskell (>=2.5.0.0 && <2.20), transformers (>=0.3 && <0.6), unordered-containers (>=0.2 && <0.3), utf8-string (>=0.3.7 && <1.1) [details]
License BSD-3-Clause
Copyright (c) 2013 Benjamin S. Scarlet and Google Inc.
Author Anthony Cowley, Stephen Diehl, Moritz Kiefer <moritz.kiefer@purelyfunctional.org>, Benjamin S. Scarlet
Maintainer Anthony Cowley, Stephen Diehl, Moritz Kiefer <moritz.kiefer@purelyfunctional.org>
Category Compilers/Interpreters, Code Generation
Home page http://github.com/jappeace/llvm-party/
Bug tracker http://github.com/jappeace/llvm-party/issues
Source repo head: git clone git://github.com/jappeace/llvm-party.git -b llvm-12
Uploaded by Jappie at 2023-06-27T02:43:26Z

Modules

Flags

Automatic Flags
NameDescriptionDefault
shared-llvm

link against llvm shared rather than static library

Enabled
llvm-with-rtti

assume llvm was built with LLVM_ENABLE_RTTI=ON (default is OFF)

Disabled
debug

compile C(++) shims with debug info for ease of troubleshooting

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for llvm-party-12.1.0

[back to package description]

llvm-party - Haskell bindings for LLVM

Build Status Hackage

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.

This is yet another fork of llvm. Specifically llvm-hs/llvm-hs-pure was forked, and smashed together into a single package.

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.

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.