DOCSEARCHbyAlgolia
Submit Docs

ghc-lib

repository·master·Indexed 41 days ago

https://github.com/digital-asset/ghc-lib

A standalone library providing the GHC API (parsing, analysis, and compilation) decoupled from the system's installed GHC compiler version. It includes ghc-lib-parser for Haskell code parsing and the full ghc-lib for compilation up to GHC's Core language. It allows developers to support multiple GHC versions or experimental features without upgrading their entire toolchain, though it does not provide a runtime or package database.

Tokens
1K
Snippets
3
Records
5
Agent score
1%

What's inside ghc-lib

  1. Overview of ghc-lib and ghc-lib-parser

    master

    The ghc-lib project provides a way to use the GHC API as a library independently of the specific GHC compiler version installed on your system. This allows you to mix and match GHC API versions and work with different GHC versions within the same tool without heavy C preprocessor usage.

    There are two primary packages:

    1. ghc-lib-parser: A subset of the GHC API sufficient for parsing Haskell code. It can serve as a replacement for haskell-src-exts.
    2. ghc-lib: Extends and re-exports ghc-lib-parser with the full GHC API.

    Key Capabilities:

    • Parse Haskell code.
    • Compile Haskell code as far as GHC's Core language (including renaming and type checking).

    Limitations:

    • No Runtime: You cannot run code produced by ghc-lib (e.g., no TemplateHaskell support).
    • No Package Database: It does not ship with a package database (like base), making it difficult to compile off-the-shelf code without building your own database.
    • Version Constraints: It can only read package databases and .hi files for one particular version of GHC at a time.

  2. How to use ghc-lib version macros

    master

    The ghc-lib-parser and ghc-lib packages use standard CPP macros for versioning.

    • Use the MIN_VERSION_pkgname(x, y, z) macros as described in the GHC user guide.
    • Note on Versioning: Builds of ghc-lib-parser/ghc-lib derived from GHC HEAD are assigned version numbers in the format 0.α (e.g., 0.20190204).

  3. Build custom ghc-lib for DAML

    master

    The CI.hs script supports building custom versions of ghc-lib tailored for the DAML compiler, which requires specific patches applied to GHC.

    When building for DAML, the --ghc-flavor flag is replaced by the --da flag, along with specific patch and base configuration flags.

    Workflow details:

    • It clones GHC and adds the DA fork of GHC as a remote named upstream (unless overridden by --upstream).
    • It checks out the commit specified by --merge-base-sha.
    • It merges commits specified via --patch flags.
    • It uses the value from --gen-flavor as the flavor argument for the ghc-lib-gen program.
    cabal run exe:ghc-lib-build-tool -- \
  --da \
  --merge-base-sha=ghc-8.8.1-release \
  --patch=upstream/da-master-8.8.1 \
  --patch=upstream/da-unit-ids-8.8.1 \
  --gen-flavor=da-ghc-8.8.1 \
     --upstream=https://github.com/digital-asset/ghc.git

  4. Install and use ghc-lib in your project

    master

    The ghc-lib-parser and ghc-lib packages are available on Hackage. Because they conflict with the standard GHC API and template-haskell, they are not exposed by default.

    To use them, you must either:

    1. Pass -package ghc-lib (or -package ghc-lib-parser) to GHC.
    2. Use the PackageImports language extension to import modules specifically from the library.

    Example using PackageImports:

    {-# LANGUAGE PackageImports #-}
import "ghc-lib" GHC.Parser
    cabal install ghc-lib

  5. Build ghc-lib from source

    master

    The easiest way to produce ghc-lib-parser and ghc-lib packages is to use the provided CI build tool. This tool creates versioned packages based on the current date and manages the version constraints between the parser and the full library.

    Requirements:

    Build Command: Execute the ghc-lib-build-tool via cabal run. You must specify a --ghc-flavor (e.g., ghc-8.8.1). Note that a flavor like ghc-9.6.1 will allow a build GHC that is at most two versions behind and not newer (e.g., [ghc-9.2.1, ghc-9.6.2)).

    # Setup
git clone git@github.com:digital-asset/ghc-lib.git
cd ghc-lib
cabal run exe:ghc-lib-build-tool -- --ghc-flavor=ghc-8.8.1