{-|
Module : LLVM
Description: An interface to use LLVM in all capacities.
Copyright: (c) Moritz Kiefer 2018
Stephen Diehl 2018
Benjamin Scarlett 2016
Maintainer: moritz.kiefer@purelyfunctional.org
-}
module LLVM (
module LLVM.Module
-- * Overview of the @llvm-hs@ library ecosystem
-- $ecosystem
-- * Constructing the C++ representation of an LLVM module
-- $moduleconstruction
-- * #objectcode# Generating object code
-- $objectcode
-- * #jitcompilation# JIT compilation
-- $jitcompilation
) where
import LLVM.Module
import LLVM.AST ()
{- $ecosystem
The main two libraries in the @llvm-hs@ ecosystem are @llvm-hs-pure@
and @llvm-hs@.
* @llvm-hs-pure@ defines a pure Haskell representation of the LLVM
AST. It has no dependency on the LLVM C/C++ libraries so even if you
have trouble installing those or want to avoid that dependency, you
should be able to use it. The documentation
in [LLVM.AST](https://hackage.haskell.org/package/llvm-hs-pure/docs/LLVM-AST.html)
describes the different options for constructing the AST.
* @llvm-hs@ then builds upon @llvm-hs-pure@ and provides the actual FFI
bindings to LLVM’s C++ libraries. Most importantly this includes
bidirectional conversions from the Haskell representation of an LLVM
module to the C++ representation and the other way around.
Once you have constructed the C++ representation, there are two main options:
1. Generate object code as described in "LLVM#objectcode"
2. or JIT compile the module as described in "LLVM#jitcompilation".
In addition to @llvm-hs@ and @llvm-hs-pure@, there are a couple of
other libraries that you be interested in:
* [llvm-hs-pretty](https://hackage.haskell.org/package/llvm-hs-pretty)
a pure Haskell prettyprinter for the AST in @llvm-hs-pure@. This is
useful if you just want to render your AST to LLVM’s textual IR
format either for debugging purposes (@llc@ will usually give pretty
good error messages for invalid IR) or because you prefer to call
the LLVM CLI tools over the linking against the LLVM libraries.
* [llvm-hs-typed](https://github.com/llvm-hs/llvm-hs-typed) contains a
strongly-typed wrapper for the AST in @llvm-hs-pure@ which makes it
harder to accidentally construct invalid LLVM IR.
* [llvm-hs-quote](https://github.com/llvm-hs/llvm-hs-quote) contains a
Haskell quasiquoter that can be used for splicing larger chunks of
existing LLVM IR into your Haskell code.
Finally, there is a [translation](https://github.com/llvm-hs/llvm-hs-kaleidoscope) of
LLVM’s official Kaleidoscope tutorial to @llvm-hs@ and you can find
small, self-contained examples covering various parts of the API in
the [llvm-hs-examples](https://github.com/llvm-hs/llvm-hs-examples)
repository.
-}
{- $moduleconstruction
Interacting with the LLVM libraries requires that you first construct
the C++ representation of an LLVM `Module`.
The most common way of doing that is to first construct the Haskell
representation of an LLVM module using @llvm-hs-pure@. You can then
use `withModuleFromAST` to convert the Haskell AST to the C++
representation.
Alternatively, you can also construct a module from LLVM’s textual IR
or the binary bitcode format using `withModuleFromLLVMAssembly` and
`withModuleFromBitcode`.
-}
{- $objectcode
Once you have constructed the C++ representation of an LLVM `Module`,
you can generate an object file using `moduleObject` which will give
you a `Data.ByteString.ByteString` or write it to a file using
`writeObjectToFile`. To construct the `TargetMachine` for these
functions you can use `LLVM.Target.withHostTargetMachine` if you want
to generate object code for the machine you are currently running on
or use `LLVM.Target.withTargetMachine` and customize the target
machine based on your needs.
-}
{- $jitcompilation
In addition to generating object code, you can also JIT-compile LLVM
modules and call functions in the resulting `Module` from Haskell.
LLVM has several JIT compilers but ORC JIT is the one that is actively
being developed and the one best supported by @llvm-hs@.
Since ORC JIT is still in active development in LLVM, the API is likely to
change regularly. See the
[Kaleidoscope](https://github.com/llvm-hs/llvm-hs-kaleidoscope) project for the
most up-to-date example of using ORC JIT.
-}