Common Architecture for Building Applications and Libraries
   Next

Common Architecture for Building Applications and Libraries

User's Guide

Table of Contents

1. Introduction
2. Packages
3. Creating a package
3.1. Package descriptions
3.1.1. Package properties
3.1.2. Library
3.1.3. Executables
3.1.4. Build information
3.1.5. Configurations
3.1.6. Source Repositories
3.2. Accessing data files from package code
3.3. System-dependent parameters
3.4. Conditional compilation
3.5. More complex packages
4. Building and installing a package
4.1. setup configure
4.1.1. Programs used for building
4.1.2. Installation paths
4.1.3. Controlling Flag Assignments
4.1.4. Miscellaneous options
4.2. setup build
4.3. setup makefile
4.4. setup haddock
4.5. setup hscolour
4.6. setup install
4.7. setup copy
4.8. setup register
4.9. setup unregister
4.10. setup clean
4.11. setup test
4.12. setup sdist
5. Reporting bugs and deficiencies
6. Stability of Cabal interfaces
6.1. Cabal file format
6.2. Command-line interface
6.2.1. Very Stable Command-line interfaces
6.2.2. Stable Command-line interfaces
6.2.3. Unstable command-line
6.3. Functions and Types
6.3.1. Very Stable API
6.3.2. Semi-stable API
6.3.3. Unstable API
6.4. 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.

1. 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
   Next
   2. Packages