The sole requirement of an Cabal package is that it should contain, in the root of its file structure, (a) a package description file Setup.description, and (b) a setup script, Setup.lhs. This section specifies the syntax of the package description, and the command-line interface for the setup script.
Here is a sample package description file:
-- 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
...
The Name, Version, License, and Copyright are compulsory.The rest of the lines are optional. Any fields the system doesn't understand will be ignored (to allow addition of fields at a later date, or to allow Setup script authors to provide their own fields). Each field must begin with "Field-Name:".
Lines beginning with "--" will be considered comments and ignored.
Each field must begin with "Field-Name:". In order to allow for long fields, any line that begins with whitespace will be considered part of the previous field.
As given, there should be no reason to have completely empty lines (except perhaps for the last line in the file). In the future, if there is need to add more records, they will be separated by at least one completely empty line.
For the Cabal-provided simple build infrastructure, the package description fields and syntax are given in Section 5.2.
Here is the command-line interface the setup script must satisfy.
Table 2. setup.lhs interface
| ./Setup.lhs configure [flags] | Prepare to build the package. Typically, this step checks that the target platform is capable of building the package, and discovers platform-specific features that are needed during the build. |
| ./Setup.lhs build | Make this package ready for installation. For a true compiler, this step involves compiling the Haskell source code. Even for an interpreter, however, it may involve running a pre-processor. |
| ./Setup.lhs install [install-prefix] | Copy the files into the install locations, and register the package with the compiler. |
./Setup.lhs register | Register (or un-register) this package with the compiler. (NB: registration is also done automatically by install.) |
| ./Setup.lhs clean | Clean out the files created during the configure, build, or register steps. |
| ./Setup.lhs test | Run the package's test suite. |
For wrapped make-based systems (for instance), a command-line parser that understands the standard Setup.lhs command-line syntax will be provided as a library.
The command ./Setup.lhs configure prepares to build the package. For sophisticated packages, the configure step may perform elaborate checks, to gather information about the target system. It may write a file to record its results, but the name and format of this file are not part of the specification.
All flags are optional. The flags are these:
--with-compiler=path, --ghc, --nhc, --hugs: specifies which compiler to use. At most one of the value of these flags may be specified. The configure step checks that the compiler is available, in a sufficiently up-to-date form for the package, and that the package expects to work with that compiler. If the compiler name is not specified, Setup.lhs will choose one; some packages will come with one compiler baked in.
--prefix=path: specifies where the installed files for the package should be installed (ie the location of the files themselves). Typically on Unix this will be /usr/local and on Windows it will be Program Files. The setup script will use a sensible default (often platform-specific) if the flag is not specified.
Unrecognized flags are errors in the default build system, but may be meaningful to wrapped make-based systems (for instance). Therefore, the provided command-line parser will pass unrecognized command-line flags on to the wrapped system.
It is OK for these flags to be "baked into" the compiled tool. In particular, the build system may bake the installation path into the compiled files. There is no provision for changing these baked-into values after configuration.
The command ./Setup.lhs build makes this package ready for installation. It takes no flags.
The command ./Setup.lhs install copies files from the built package to the right location for installed files, specified in the configure step. Then it registers the new package with the compiler, using the hc-pkg command.
--install-prefix=path: specifies where the installed files for the package should be installed (ie the location of the files themselves). It has three effects. First, it over-rides the --prefix flag specified in the configure step, providing an alternative location. Second, it does not call hc-pkg to register the package. Instead, third, it creates an installed package description file, installed-pkg-descr, which can later be fed to hc-pkg.
--user: if present, this flag is passed to hc-pkg so that the package is registed for the current user only. This flag has no effect if --install-prefix is used, because in that case hc-pkg is not called.
--global: if present, this flag is passed to hc-pkg so that the package is registed globally (this is the default if neither --user or --global are given). This flag has no effect if --install-prefix is used, because in that case hc-pkg is not called.
The reason for the --install-prefix flag is that Roland RPM wants to create an exact installation tree, all ready to bundle up for the target machine, but in a temporary location. He cannot use this location for --prefix in the configure step, because that might bake the wrong path into some compiled files. Nor does he want to register this temporary tree with the compiler on his machine. Instead, he bundles up the temporary installation tree, plus the installed-pkg-descr, and ships them all to the target machine. When they are installed there, the post-installation script runs hc-pkg on the installed-pkg-descr file.
Note that there is no uninstall command in the setup script. While it would be easy enough to implement in the simple build infrastructure, we don't want to require make-based build systems to implement make uninstall, which is fairly non-standard and difficult to get right. In the majority of cases, we expect libraries to be installed via a package manager (eg. RPM, Debian APT), which already provide uninstallation services.
The command ./Setup.lhs register registers the now-installed package with the compiler. Similarly, ./Setup.lhs unregister un-registers the package.
--global: registers/un-registers a package as global. This is the default.
--user: registers/un-registers a package for the current user only.
Bob the Builder can install a Cabal source distribution thus. He downloads the source distribution and unpacks it into a temporary directory, cd's to that directory, and says
./Setup.lhs configure --ghc ./Setup.lhs build ./Setup.lhs install --userSimilarly, Sam Sysadmin does exactly the same, except that he says
./Setup.lhs install --globalin the final step, so that the package is installed where all users will see it.
For a binary distribution, both Bob and Sam would omit the first two steps, and just do the install step.
System packagers, such as Peter Packager or Donald Debian, will run the configure and build steps just like Bob and Sam. A that point, Donald will say
./Setup.lhs install --install-prefix=/tmp/donald
to construct a ready-to-zip tree of all the
installed files, plus a file
installed-pkg-descr that describes the
installed package. He arranges to deliver both these
components to the target machine, and then feed
installed-pkg-descr to hc-pkg on the
target machine. The file installed-pkg-descr also contains information he needs for building his Debian distribution, namely the package name, version, and (exact) dependencies.
We expect there to be additional tools to help System Packagers to prepare the materials necessary to build their packages from a source distribution. For example, an RPM tool could take a Haskell package source distribution and build an initial .spec file with as many of the fields as possible filled in automatically. In most cases some intervention by the System Packager will be necessary; for example platform-specific dependencies may need to be specified.
After Peter has constructed the package, Isabella can install it in a manner she is comfortable with.