Common Architecture for Building Applications and Libraries

User's Guide


Table of Contents

Introduction
Packages
Creating a package
Package descriptions
Package properties
Library
Executables
Build information
Configurations
Source Repositories
Accessing data files from package code
System-dependent parameters
Conditional compilation
More complex packages
Building and installing a package
setup configure
Programs used for building
Installation paths
Controlling Flag Assignments
Miscellaneous options
setup build
setup makefile
setup haddock
setup hscolour
setup install
setup copy
setup register
setup unregister
setup clean
setup test
setup sdist
Reporting bugs and deficiencies
Stability of Cabal interfaces
Cabal file format
Command-line interface
Very Stable Command-line interfaces
Stable Command-line interfaces
Unstable command-line
Functions and Types
Very Stable API
Semi-stable API
Unstable API
Hackage

Abstract

Cabal aims to simplify the distribution of Haskell software. It does this by specifying a number of interfaces between package authors, builders and users, as well as providing a library implementing these interfaces.

Introduction

Developers write Cabal packages. These can be for libraries or executables. This involves writing the code obviously and also creating a .cabal file. The .cabal file contains some information about the package. Some of this information is needed to actually build the package and some is just useful for identifying the package when it comes to distribution.

name:     Foo
version:  1.0

library
  build-depends:   base
  exposed-modules: Foo
    

Users install Cabal packages so they can use them. It is not expected that users will have to modify any of the information in the .cabal file. Cabal does provide 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.

tar -xzf Foo-1.0.tar.gz
cd Foo-1.0
runhaskell Setup configure --with-compiler=ghc-6.4.2 --user
runhaskell Setup build
runhaskell Setup install
    

One of the purposes of Cabal is to make it easier to build a package with different Haskell implementations. So it provides abstractions of features present in different Haskell implementations and wherever possible it is best to take advantage of these to increase portability. Where necessary however it is possible to use specific features of specific implementations. For example one of the pieces of information a package author can put in the package's .cabal file is what language extensions the code uses. This is far preferable to specifying flags for a specific compiler as it allows Cabal to pick the right flags for the Haskell implementation that the user picks. It also allows Cabal to figure out if the language extension is even supported by the Haskell implementation that the user picks. Where compiler-specific options are needed however, there is an "escape hatch" available. The developer can specify implementation-specific options and more generally there is a configuration mechanism to customise many aspects of how a package is built depending on the Haskell implementation, the Operating system, computer architecture and user-specified configuration flags.

name:     Foo
version:  1.0

library
  build-depends:   base
  exposed-modules: Foo
  extensions:	   ForeignFunctionInterface
  ghc-options:     -Wall
  nhc98-options:   -K4m
  if os(windows)
    build-depends: Win32