Liquid Haskell integration for Cabal and stack
Haskell
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src/LiquidHaskell
.gitignore
LICENSE
README.md
Setup.hs
liquidhaskell-cabal.cabal
stack.yaml

README.md

liquidhaskell-cabal

Liquid Haskell integration for Cabal and Stack.

Hackage Hackage-Deps

liquidhaskell-cabal provides drop-in LiquidHaskell integration for projects built with Cabal and/or Stack.

Setting Up

(See liquidhaskell-cabal-demo for an example project setup.)

  1. Make sure you have LiquidHaskell version 0.6 or above installed and available in your $PATH.

  2. Open up your Setup.hs file. For most projects, it will look like this:

    import Distribution.Simple
    main = defaultMain
    

    Replace that with:

    import LiquidHaskell.Cabal
    main = liquidHaskellMain
    

    This hooks LiquidHaskell into your Cabal/Stack-based build.

    (For projects already using a custom Setup.hs file, see the section "Custom Setup.hs Files" below.)

  3. Next, it's time to set up your project's .cabal file.

    Add liquidhaskell-cabal to the build-depends lists of each of your libraries and executables:

    library
      build-depends: {- ... other dependencies ... -}
                   , liquidhaskell-cabal >= 0.1.1
                     {- ... perhaps more dependencies? ... -}
    

    Then add a custom-setup stanza at the top level, outside the library and executale sections:

    custom-setup
      setup-depends: base, Cabal, liquidhaskell-cabal >= 0.1.1
    

    This tells Cabal to make the base, Cabal, and liquidhaskell-cabal packages available when building Setup.hs. It goes at the top level of your .cabal file, next to library, executable, and test-suite. And as with other setup-depends lists, you can optionally set version bounds here.

    You'll also need a flag called liquidhaskell in your .cabal file; liquidhaskell-cabal only activates if it sees that a flag with this name is enabled. It is highly recommended that this be disabled by default, so that end users of your package don't need to know about LiquidHaskell to install it:

    flag liquidhaskell
      description: After building, verify with LiquidHaskell
      default:     False
    

    Finally, make sure the build-type field in your .cabal file is set to Custom (most projects use Simple):

    build-type: Custom
    

    Each library and executable in your package can optionally specify its own LiquidHaskell flags; see the section "Custom LiquidHaskell Flags" below for more on that.

  4. When building, you may see a warning that looks like:

    Ignoring unknown section type: custom-setup
    

    This is because Cabal won't actually recognize the custom-setup stanza until version 1.24 and above. If you're building with Stack, see the next step; otherwise, you'll need to install liquidhaskell-cabal manually to make it available to your Setup.hs:

    $ cabal install liquidhaskell-cabal-0.1.1.0
    
  5. If you're building with Stack, add the following to your project's stack.yaml:

    explicit-setup-deps:
      "*": true
    extra-deps:
      - liquidhaskell-cabal-0.1.1.0
    

    (If your stack.yaml already has an extra-deps list, add liquidhaskell-cabal-0.1.1.0 to the existing one instead of starting a second list.)

That's it! You should be good to go.

Usage

If you're using Stack, you can build and check with LiquidHaskell by adding --flag <package name>:liquidhaskell to your stack build command:

stack build --flag mypackage:liquidhaskell

Otherwise, pass -fliquidhaskell to cabal configure to switch on LiquidHaskell checking for your builds:

cabal configure -fliquidhaskell && cabal build

(Running cabal configure without -fliquidhaskell will turn it back off.)

Custom LiquidHaskell Flags

Each library and executable in your package can specify its own extra command line flags to pass to LiquidHaskell (these are described in the LiquidHaskell README). Simply add an x-liquidhaskell-options field to the relevant components:

library
  (... other fields ...)
  x-liquidhaskell-options: --diff --no-termination

executable myexecutable
  (... other fields ...)
  x-liquidhaskell-options: --diff

Custom Setup.hs Files

For most projects, the simple Setup.hs file given above (using liquidHaskellMain) should be sufficient. However, for those already using custom Setup.hs files, the LiquidHaskell.Cabal module (Haddock) provides more granular means of hooking LiquidHaskell into the build process.

liquidHaskellHooks is a Cabal UserHooks structure pre-configured for LiquidHaskell. Using it, the basic Setup.hs file is equivalent to:

import Distribution.Simple
import LiquidHaskell.Cabal
main = defaultMainWithHooks liquidHaskellHooks

liquidHaskellPostBuildHook is the Cabal postBuild hook that actually configures and runs LiquidHaskell. Using it, the above is equivalent to:

import Distribution.Simple
import LiquidHaskell.Cabal
main = defaultMainWithHooks $
  simpleUserHooks { postBuild = liquidHaskellPostBuildHook }

Projects already using a postBuild hook can invoke liquidHaskellPostBuildHook from within it, passing in the appropriate arguments:

import Distribution.Simple
import LiquidHaskell.Cabal

main = defaultMainWithHooks $
  simpleUserHooks { postBuild = myFancyHook }

myFancyHook :: Args -> BuildFlags -> PackageDescription -> LocalBuildInfo -> IO ()
myFancyHook args buildFlags pkgDesc lbi = do
  {- ... other important code ... -}
  liquidHaskellPostBuildHook args buildFlags pkgDesc lbi
  {- ... even more code ...-}