1.1. Dramatis personae

The HPS serves a number of different people:

• 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.

• Roland RPM, Donald Debian, and Willie Windows build Linux RPM, Debian, and Windows installer packages respectively (this list is not exhaustive). They do this as a service for Angela Author and the community, and may know little or nothing about the internal details of the Haskell packages they are wrapping up.

• 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.

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 HPS 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 HPS 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/pkg.desc:

    name:     angela-coll
    version:  1

She also creates a three-line Haskell file ~/coll/Setup.lhs as follows:

  #! runhugs

  > import Distribution.Simple( main )

The first line arranges that when Angela executes Setup.lhs as a shell script, the shell will invoke runhugs, which will in turn run main imported from the library Distribution.Simple. This library implements the HPS simple build infrastructure.

Now she is ready to go. She types:

  ./Setup.lhs configure --ghc
  ./Setup.lhs build
  ./Setup.lhs src-dist

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.