Cabal User Guide

Cabal specifies a standard way in which Haskell libraries and applications can be packaged so that it is easy for consumers to use them, or re-package them, regardless of the Haskell implementation or installation platform.

Cabal defines a common interface – the Cabal package – between package authors, builders and users. There is a library to help package authors implement this interface, and a tool to enable developers, builders and users to work with Cabal packages.

Introduction

Cabal is package system for Haskell software. The point of a packaging system is to enable software developers and users to easily distribute, use and reuse software. A good packaging system makes it easier for developers to get their software into the hands of users, but equally importantly it makes it easier for software developers to be able to reuse software components written by other developers.

Packaging systems deal with packages and with Cabal we call them Cabal packages. The Cabal package is the unit of distribution. Every Cabal package has a name and a version number which are used to identify the package, e.g. filepath-1.0.

Cabal packages are source based and are typically (but not necessarily) portable to many platforms and Haskell implementations. The Cabal package format is designed to make it possible to translate into other formats, including binary packages for various systems.

Note that packages are not part of the Haskell language, but most Haskell implementations have some notion of package, and Cabal supports most Haskell implementations.

What’s in a package

A Cabal package consists of:

Haskell software, including libraries, executables and tests

meta-data about the package in a standard human and machine readable format (the “.cabal” file)

a standard interface to build the package (the “Setup.hs” file)

The .cabal file contains information about the package, supplied by the package author. Some of this information is used for identifying and managing the package when it comes to distribution.

For the majority of packages it is possible to supply enough information in the .cabal file so that it can be built without the package author needing to write any extra build system scripts. For complex packages it may be necessary to add code to the Setup.hs file.

Here is an example foo.cabal for a very simple Haskell library that exposes one Haskell module called Data.Foo:

For full details on what goes in the .cabal and Setup.hs files, and for all the other features provided by the build system, see the section on developing packages.

A tool for working with packages

There is a command line tool, called cabal, that users and developers can use to install Cabal packages. It can be used for both local packages and for packages available remotely over the network.

Developers can use the tool with packages in local directories, e.g.

cd foo/
cabal install

Developers and users can use the tool to install packages from remote Cabal package archives. By default, the cabal tool is configured to use the centeralised Haskell community archive called Hackage but it is possible to use it with any other suitable archive.

cabal install xmonad

This will install the xmonad package plus all of its dependencies.

Cabal provides a number of ways for a user to customise how and where a package is installed. They can decide where a package will be installed, which Haskell implementation to use and whether to build optimised code or build with the ability to profile code. It is not expected that users will have to modify any of the information in the .cabal file.