Actually two components:

• The library part (Cabal package, bundled with GHC)
• The front-end tool cabal (cabal-install package)

GHC uses Cabal mostly for parsing CABAL package descriptions (→ ghc-pkg)

• The "A.B" components are called major version
• The "c" component is called minor version
• The "x.y.…" components are optional

Lexicographic ordering applied: e.g. 2.1 > 1.3 and 2.1.1 > 2.1

An API breaking change requires a major version increment;
(Non-breaking) API additions require a minor version increment;
For other non-semantic changes "x.y.…" shall be incremented

If the PVP is followed, this allows a packages to be compatible with a certain range of newer package versions.

Recommended practice: use qualified or explicit imports, e.g.

import qualified Data.Text as T
import Data.Text.Encoding (decodeLatin1) -- 0.11.3+

This way, the text dependency can be safely declared as

build-depends: text >=0.11.3 && <0.12

If it turns out, that a future text-0.12.0 won't break anything relevant to us, we can bump the upper limit to <0.13 (→ versioning avalanche hazard!)

cabal update update package index

1. Computes install-plan for cool-package based on package index
2. If successful, downloads cool-package + missing dependencies
3. Recursively build and install dependencies and finally cool-package

• User local packages (default install location)
• System-wide packages (e.g. GHC packages or packages provided by Linux distro)

Install paths can be customized via ~/.cabal/config

• ~/.cabal/bin/ installed executable(s) (add to $PATH!)
• ~/.cabal/lib/ contains compiled and .hi interface files
• ~/.cabal/share/ contains package data and Haddock docs

• Look at it with ghc-pkg list --user

• cabal collects all packages installed in world-file
• Virtual world package: cabal install world
• Useful when needing to recompile everything (GHC upgrade, profiling flags)

• E.g. cabal install alex will install alex over and over again
• Don't build-depends on executable-only packages!

• this only unregisters package from ~/.ghc/

• Remove ~/.ghc/
• Remove ~/.cabal/{lib,logs,share}/

Create your project, e.g. like

./src/Data/Objects.hs
./src/Data/Objects/Internal.hs
…

Just run cabal init, answer the questions, and if lucky you'll get a working <pkg-name>.cabal file

A .cabal file starts with top-level meta infos about the package.

• at most one library target and
• an arbitrary number of executable/test-suite/benchmark targets.

• via main-is/exposed-modules/other-modules or else
• cabal sdist will fail to include them.

• Can be used to implement conditional compilation
  (via #ifdefs or including/excluding modules as a whole from compilation)
• Can also modify build-depends (not recommended if avoidable)
  cabal will backtrack through (non-manual) flags
• cabal configure --flags="debug -usebytestring"

• Note: Use same build-dep influencing flags as for configure below!

• The build artifacts can be found in dist/build/<target>/

• -s is short for --save-configure

• combines cabal {install --only-dep, configure, build, haddock}
• plus copying artifacts into ~/.cabal and registering with ghc-pkg

How to install latest cabal-install snapshot:

cd /tmp
git clone git://github.com/haskell/cabal.git
(cd cabal/Cabal         && cabal install)
(cd cabal/cabal-install && cabal install)
rm -rf /tmp/cabal

New cabal executable should be at ~/.cabal/bin/cabal

New feature: Per-project ./cabal.config overrides ~/.cabal/config

Quick usage primer:

cabal sandbox init
cabal {configure,build,install,…}
cabal sandbox delete

Sandbox mode enabled if ./cabal.sandbox.config present

Augment sandbox-local view of Hackage package index:

cabal sandbox add-source [--snapshot] <source-folder>
cabal sandbox list-sources
cabal sandbox delete-source <list-source-folder>

add-source injects the given package into the package index, and makes it available for

cabal info
cabal list
cabal configure
cabal install

For operating on the sandboxed GHC package registry (i.e. ghc-pkg {list,…}):

cabal sandbox hc-pkg …

cabal sandbox is still work-in-progress and you can report issues!

Stay tuned for cabal ghci support

Variant of executable targets, with additional field

type: exitcode-stdio-1.0

Tests & benchmarks need to generate report somewhere to be useful

Enable via cabal configure --enable-tests --enable-benchmarks
(optional with bleeding edge cabal-install)

Run via cabal test or cabal bench
and pass options via --{test,benchmark}-options="…"

criterion-based benchmarks are perfectly fine for use with cabal benchmark

cabal bench bench1 --benchmark-options="-o bench1-report.html --junit bench1.xml"

• use the HTML Publisher Plugin to publish the HTML
• or Performance Plugin to monitor performance trends.

• test-framework-golden
• test-framework-hunit
• test-framework-quickcheck2
• test-framework-smallcheck

Configure with

cabal configure --enable-tests --enable-library-coverage

Now cabal test will produce coverage reports via hpc

Currently semi-broken (can be workarounded):

Warning: Your version of HPC (0.6) does not properly handle multiple search paths. Coverage report generation may fail unexpectedly. These issues are addressed in version 0.7 or later (GHC 7.8 or later).