1.1. Dramatis personae

The Cabal serves a number of people in different ways:

• Joe User is simply a Haskell user. He does not download new packages. Nevertheless, he needs to know about his Haskell compiler's -package flag (see Section 3).

• Bob the Builder and Sam Sysadmin both download, build, and install new packages. The only difference between the two is that Sam has root permission, and can install packages in more globally-visible places.

• Peter Packager builds operating system specific install files (e.g. .msi .rpm .deb) from packages supplied by Marcus or Angela. We might also call him Roland RPM, Donald Debian, and Willie Windows who build Linux RPM, Debian, and Windows installer packages respectively (this list is not exhaustive). They do this as a service to their platform's community, and may know little or nothing about the internal details of the Haskell packages they are wrapping up.

• Isabella Installer installs binary packages supplied by Peter or Angela, (or Rowland, Donald, and Willie). Isabella requires only a Haskell compiler/interpreter. She can use rpm to install packages by Rowland. She cannot or will not build the packages herself, so she relies on Peter to provide them. She won't use the Setup script directly from Angela, but she might use a layered tool like haskell-install, which does all the work of downloading and installing simple packages.

• Angela Author wants to write a simple Haskell tool, and distribute it with minimum fuss, in such a way that all the above folk can easily use it.

• Marcus Makefile is like Angela, but more sophisticated. He has a complicated tool, and uses makefiles. Still, he wants to arrange that Roland, Donald, Bob, Sam, and Joe don't need to know about his internal complexity.

We describe Angela and Marcus as producers of their packages, and all the others as package consumers.

Note that though these users all have different names, it is very common for their roles to overlap when it comes to real people. For instance, if Bob builds packages for himself, he becomes Joe once they're built. These personas are use cases, and not meant to represent completely distinct individuals.

1.2. An example

To give the idea, here is a simple example. Angela has written a couple of Haskell modules that implement sets and bags; she wants to distribute them to Bob as a package called, say, angela-coll. Let's say that the modules are Data.Set, Data.Bag, Angela.Internals. (The Cabal says nothing about how Angela decides where in the name space to put her modules.) Angela only wants to expose the first two to Bob; the Angela.Internals module is (as its name suggests) internal to the package.

Angela decides to use the simple build infrastructure that the Cabal provides. She is working in a directory ~/coll. In there she puts the modules, in sub-directories driven by their module name: ~/coll/Data/Set.hs, ~/coll/Data/Bag.hs, and ~/coll/Angela/Internals.hs. Next, she writes a package description, which she puts in ~/coll/Setup.description:

Name: angela-coll
Version: 0.1.1.1.1-foo-bar-bang
License: LGPL
Copyright: Copyright (c) 2004, Angela Author
Exposed-Modules: A, B, B.C

She also creates a small Haskell file ~/coll/Setup.lhs as follows:

  #! /usr/bin/env runhugs

  > module Main where
  > import Distribution.Simple( defaultMain )
  > main = defaultMain

This library implements the Cabal simple build infrastructure.

The first line arranges that when Angela, (or Joe, or Sam, etc.) executes Setup.lhs as a shell script, the shell will invoke runhugs, which will in turn run mainn imported from the library Distribution.Simple.

It is not necessary that the script be run this way, it is just a convinient way to run it. Sam or Joe may choose to compile the setup script into an executable with NHC or GHC and then run it directly (it is a literate Haskell script so that it can be compiled without the first line causing a syntax error). Another option is for that first line to read

!# /usr/bin/env runhaskell

where runhaskell is a symlink to runhugs, runghc, or runnhc.

Now she is ready to go. She types:

  ./Setup.lhs configure --ghc
  ./Setup.lhs build
  ./Setup.lhs sdist

The first line readies the system to build the tool using GHC; for example, it checks that GHC exists on the system. The second line checks that the tool does indeed build flawlessly. (At this point she can write and execute tests, as we discuss later.) The third line wraps up the package as a source distribution, making the file ~/coll/angela-coll-1.tar.gz.

Angela emails the tar file to Bob, who untars it into tmp/coll. He cd's to that directory and types

  ./Setup.lhs configure --ghc
  ./Setup.lhs build
  ./Setup.lhs install

He's all done. Now in his Haskell programs, Bob can simply import the new modules Data.Set and Data.Bag. He does not need to give extra flags to GHC to tell it to look for Angela's modules; they are there automatically. If Angela used the same module names as someone else, Bob may need finer control: see Section 3.

If Angela wrote her modules in a suitably portable variant of Haskell, Bob could also have said --hugs or --nhc in his configure line, and the package would have been built and installed for those compilers instead.