cabal - the simple guide

just a simple guide for getting started with cabal.


by katychuang
inspired by the git guide
please report issues on github


1. Installation

Download Cabal and cabal-install
source (Linux/OSX/Win)

You'll need at least this version
cabal --version
cabal-install version
using version of the Cabal library

2. create a sandbox

create a new directory, open it and type
cabal sandbox init
to create a new sandbox in a subdirectory
of your current folder .cabal-sandbox

3. hackage package list

update your local list of packages and dependencies, with
cabal update
this will get the newest versions listed on Hackage

4. external dependencies

create a copy of a package by running the command
cabal install
Some flags can speed up this process
-jN to build N packages in parallel
--dry-run to see what cabal plans to do (recommended)

5. build application

your sandbox consists of specific local version of packages you've just added and your project can be built with
cabal build

you can find your executables in dist/build directory

6. Freeze

Introduced in Cabal version 1.20
cabal freeze
is useful when building an application.
It produces a list of packages with their version numbers.

7. Repl

You can play around with the code in GHCi:
cabal repl
This is much faster than rebuilding the executable
after every single change.
It is a ghci console, where you can :r reload the file.

8. Troubleshooting

Sometimes different versions can cause build errors.
List all the registered packages:
ghc-pkg list
In special cases when you want to unregister specific packages:
ghc-pkg unregister packageName-0.0.1

useful hints

attaching patched or an unreleased version of a library
cabal sandbox add-source
delete sandbox
cabal sandbox delete
alternative manual clean
rm -rf .cabal-sandbox cabal.sandbox.config

links & resources