Common Architecture for Building Applications and Libraries

User's Guide


Table of Contents

1. Packages
2. Creating a package
2.1. Package descriptions
2.1.1. Package properties
2.1.2. Library
2.1.3. Executables
2.1.4. Build information
2.2. Accessing data files from package code
2.3. System-dependent parameters
2.4. More complex packages
3. Building and installing a package
3.1. setup configure
3.1.1. Programs used for building
3.1.2. Installation paths
3.1.3. Miscellaneous options
3.2. setup build
3.3. setup haddock
3.4. setup install
3.5. setup copy
3.6. setup register
3.7. setup unregister
3.8. setup clean
3.9. setup test
3.10. setup sdist
4. Known bugs and deficiencies

Abstract

The 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. Packages

A package is the unit of distribution for the Cabal. Its purpose, when installed, is to make available either or both of:

  • A library, exposing a number of Haskell modules. A library may also contain hidden modules, which are used internally but not available to clients.[1]

  • One or more Haskell programs.

However having both a library and executables in a package does not work very well; if the executables depend on the library, they must explicitly list all the modules they directly or indirectly import from that library.

Internally, the package may consist of much more than a bunch of Haskell modules: it may also have C source code and header files, source code meant for preprocessing, documentation, test cases, auxiliary tools etc.

A package is identified by a globally-unique package name, which consists of one or more alphanumeric words separated by hyphens. To avoid ambiguity, each of these words should contain at least one letter. Chaos will result if two distinct packages with the same name are installed on the same system, but there is not yet a mechanism for allocating these names. A particular version of the package is distinguished by a version number, consisting of a sequence of one or more integers separated by dots. These can be combined to form a single text string called the package ID, using a hyphen to separate the name from the version, e.g. “HUnit-1.1”.

Note

Packages are not part of the Haskell language; they simply populate the hierarchical space of module names. It is still the case that all the modules of a program must have distinct module names, regardless of the package they come from, and whether they are exposed or hidden. This also means that although some implementations (i.e. GHC) may allow several versions of a package to be installed at the same time, a program cannot use two packages, P and Q that depend on different versions of the same underlying package R.



[1] Hugs doesn't support module hiding.