5. The Cabal simple build infrastructure

5.1. Overview

The simple build infrastructure works as follows. First, Angela puts the following Haskell file Setup.lhs in the root of her tree:

  #! /usr/bin/env runghc

  > import Distribution.Simple

Second, she writes a package description Setup.description in the syntax of Section 5.2, which describes the package and gives extra information to the simple build infrastructure.

Now Angela can build her package by saying

  ./Setup.lhs configure
  ./Setup.lhs build

She can even install it on her own machine by saying

  ./Setup.lhs install

She can build a Cabal source distribution:

  ./Setup.lhs source-dist

The full details are given in Section 5.3.

It is no coincidence that the interface is very similar to that for the setup script for an Cabal package distribution (Section 4). In fact, Distribution.Simple.defaultMain conforms to the specification of Section 4.2, and when it builds a distribution, it includes ./Setup.lhs in the tarball, ready to be run by Bob the Builder. However, Distribution.Simple.defaultMain of course implements a richer interface than that required by Section 4.2, because it's intended to support Angela as well as Bob. The full specification is in Section 5.3.

5.2. Package description in the simple build infrastructure

When using the simple build infrastructure, the package description file Setup.description contains not only the name of the package, its version and dependencies, but also a collection of information to explain to the simple build infrastructure how to build the package. This section gives the specific fields, and the syntax of those fields. For the general syntax of the file, please see Section 4.1.

Here is a sample package description file with all the fields understood by the simple build infrastructure:

        -- Required
        Name: Cabal
        Version: 0.1.1.1.1-rain
        License: LGPL
        Copyright: Free Text String
        -- Optional - may be in source?
        Stability: Free Text String
        Build-Depends: haskell-src, HUnit>=1.0.0-rain
        Modules: Distribution.Package, Distribution.Version,
                 Distribution.Simple.GHCPackageConfig
        C-Sources: not/even/rain.c, such/small/hands
        HS-Source-Dir: src
        Exposed-Modules: Distribution.Void, Foo.Bar
        Extensions: OverlappingInstances, TypeSynonymInstances
        Extra-Libs: libfoo, bar, bang
        Include-Dirs: your/slightest, look/will
        Includes: /easily/unclose, /me, "funky, path\\name"
        Options-ghc: -fTH -fglasgow-exts
        Options-hugs: +TH

        -- Next is an executable
        Executable: somescript
        Main-is: SomeFile.hs
        Modules: Foo1, Util, Main
        HS-Source-Dir: scripts
        Extensions: OverlappingInstances

The Name, Version, License, and Copyright are compulsory.

All other fields, such as dependency-related fields, will be considered empty if they are absent. Any fields that the system does not understand will be ignored.

Note that in the future, though the Modules field will be available, it will not be necessary to provide it for building executables and libraries. Instead, the user will provide only the "Main-Is" field (for executables) and the "Exposed-Modules" field (for libraries). The system will chase down dependencies from those modules and include them in the library or source distributions.

The description file fields:

Further details on some fields:

• --PATH-- Paths are written in the Unix style, with directories separated by slashes, optionally ending in a filename. There are two kinds of paths supported: "Simple" and "Complex". "Simple" paths are alpha-numeric values separated by slashes (foo/bar/bang). More "Complex" paths such as those with spaces or non-alphanumeric characters must be put in quotes ("foo, /bar \//bang"). You should assume that the paths are case sensitive, though in practice this varies depending on the end user's file system.

• --MODULE LIST-- A module list is a standard Haskell module name, without any file suffixes (.lhs or .hs). Each module should be separated by a comma.

• --FREE TEXT-- You may put anything in these fields. For multi-line fields, start the subsequent lines with whitespace.

• --OPTIONS--The exact syntax of the options field is dependent on the compiler you're using. Refer to your compiler's man page for details. Multiple options should be separated by whitespace.

On hidden modules: Hidden modules form part of the implementation of the package, but not its interface: a client of the package cannot import an internal module. The system still must derive their existence, or they must be listed explicity for two reasons: (a) to allow the global program invariant to be checked (see Section 2.2) and (b) to enable a build system or programming environment to find the source files.

5.3. Distribution.Simple

This section gives the command line interface supported by Distribution.Simple.defaultMain. It supports all the commands described in Section 4.2, (except for "test" - FIX) and in addition the following:

Distribution.Simple.defaultMain provides interactive command-line help. For each command, a help string is available by typing "./Setup.lhs COMMAND --help".

5.4. The Makefile route

The Haskell libraries that support the simple build infrastructure can, of course, also be re-used to make setup scripts that work quite differently. At one extreme is a setup script that immediately shells out into make, which does all the work.

To support this, Cabal provides a trivial setup library Distribution.Make, which simply parses the command line arguments and shells out into make. Marcus uses the following Setup.lhs

  #! /usr/bin/env runhugs

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

All the package description information is assumed to be known to the makefile system, and so does not appear in the setup script. Thus,

  ./Setup.lhs configure --ghc

invokes

  ./configure --with-hc=ghc

Similarly ./Setup.lhs build invokes make all And so on.

Marcus simply arranges that when his makefiles build a distribution, they include this simple setup script in the root of the distribution, where the Bob the Builder expects to find it.