The GHC API, decoupled from GHC versions
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples
ghc-lib-gen
.ghci
.gitignore
.hlint.yaml
.travis.yml
CI.hs
ChangeLog.md
LICENSE
README.md
appveyor.yml
ghc-lib-gen.cabal
stack.yaml

README.md

ghc-lib Hackage version Stackage version Linux Build Status Windows Build Status

Copyright Digital Asset 2018-2019.

The GHC API allows you to use the GHC compiler as a library, so you can parse, analyze and compile Haskell code. The GHC API comes preinstalled with GHC, and is tied to that GHC version - if you are using GHC 8.6.3, you get version 8.6.3 of the API, and can't change it. The ghc-lib package solves that problem, letting you mix and match versions of the GHC compiler and GHC API. Why might you want that?

  • Imagine you are writing a tool to work with several versions of the GHC compiler. The GHC API changes significantly between each version, so doing this would require writing a lot of C preprocessor code to support it. An alternative is to use one version of ghc-lib which works across multiple versions of GHC.
  • Imagine you are modifying the GHC API or want features from GHC HEAD. With ghc-lib you can depend on the revised GHC API, without upgrading the compiler used to build everything, speeding up iteration.

While ghc-lib provides the full GHC API, it doesn't contain a runtime system, nor does it create a package database. That means you can't run code produced by ghc-lib (no runtime), and compiling off-the-shelf code is very hard (no package database containing the base library). What you can do:

There are some downsides to ghc-lib:

  • The lack of runtime means you can't run code, which includes running code at compile time, e.g. TemplateHaskell.
  • While ghc-lib isn't tied to any specific GHC versions, it can only read package databases and .hi files for one particular version of GHC. That means your existing package database probably can't be consumed by ghc-lib (unless you happen to perfectly match the GHC version, in which case you could just have used the GHC API), and it doesn't ship with a package database so you'd have to painfully build your own.
  • Compilation times for ghc-lib are not small, taking approximately 5 minutes on our CI machines.

Using ghc-lib

The package ghc-lib is available on Hackage, and can be used like any normal package, e.g. cabal install ghc-lib. Since ghc-lib conflicts perfectly with the GHC API and template-haskell, the package is hidden by default : use the language extension PackageImports to do import "ghc-lib" GHC. There are two release streams within the ghc-lib name:

  • Version 8.8.1 will be the version of ghc-lib produced against the released GHC 8.8.1, once it comes out;
  • Version 0.20190204 is the version of ghc-lib using GHC HEAD on the date 2019-02-04.

The ghc-lib Hackage package is licensed under the BSD-3-Clause license, just like GHC itself. This repo, including the examples and the script that generates ghc-lib, are licensed under the BSD-3-Clause OR Apache-2.0 license.

Creating ghc-lib

We create ghc-lib by taking a checkout of GHC, and combining the ghc package with the various dependencies it is tightly tied to (e.g. template-haskell) in one new ghc-lib.cabal. That new package depends on a few generated outputs (which we build using the GHC build system) and some Cmm files (which we hack around by editing the Haskell source, because Cabal support for Cmm files is lacking). The ghc-lib-gen directory contains a script that puts all the pieces together. Because GHC itself is capable of being bootstrapped with older GHC versions (its Stage0 build), the generated ghc-lib also compiles with multiple GHC versions.

To build ghc-lib you'll need clones of this repository and the GHC repository. In a bash shell, build with the following commands.

git clone git@github.com:digital-asset/ghc-lib.git
cd ghc-lib
git clone git://git.haskell.org/ghc.git --recursive
cabal run ghc
cd ghc
cabal install

Warning : ghc-lib is known to work on all of MacOS, Linux and Windows. A distribution produced with cabal sdist on Linux/MacOS builds on Windows, but a cabal sdist produced on Windows does not build on MacOS/Linux.

Releasing ghc-lib (notes for maintainers)

First prepare with:

cd ghc-lib
git clone git://git.haskell.org/ghc.git --recursive
cabal run ghc
cd ghc

Then edit ghc-lib.cabal to fix the version number (e.g. 0.20190204) before executing:

cabal sdist

Upload dist/ghc-lib-xxx.tar.gz to Hackage.