Cabal User Guide

Cabal is package system for Haskell software.

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.

Contents

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.

When distributed, Cabal packages use the standard compressed tarball format, with the file extension .tar.gz, e.g. filepath-1.0.tar.gz.

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:

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:

name:              foo
version:           1.0
build-type:        Simple
cabal-version:     >= 1.2

library
  exposed-modules: Data.Foo
  build-depends:   base >= 3 && < 5

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.

For full details, see the section on building and installing packages.

Note that cabal is not the only tool for working with Cabal packages. Due to the standardised format and a library for reading .cabal files, there are several other special-purpose tools.