Custom build interface

Imported from Trac wiki; be wary of outdated information or markup mishaps.

This page is about the Setup.hs command line interface for packages that use custom build systems.

Discussion

The original proposal for Cabal specifies that there should be a common interface for package build systems. This interface is intended to allow people or automatic package managers to build and install the package.

Over time, the Setup.hs command line interface provided by the default "Simple" build system has grown bigger and bigger. It has been extended to provide more features to developers and users which is a good thing of course but there is a downside. It means the standard interface has become less well defined. It should in principle be possible to have a Setup.hs with a completely custom implementation. This is hard if it is not clear what the command line interface should be and if tools like cabal-install expect an extended interface.

The other problem with the command line interface as it stands is that it serves two purposes. It is supposed to be a convenient interface for users but also for automated systems like cabal-install or distribution packaging systems (deb, rpm builders etc). Things that are convenient for users can be a pain for automated systems. For example:

• runghc Setup.hs sdist if this invokes gnu tar then it is non-portable. It does not work on windows. From the point of view of cabal-install it would be much better if sdist populated a given directory with an image of the tarball and let cabal-install check it and handle the issue of preparing a .tar.gz file. See issue #365, issue #403.
• runghc Setup.hs clean if this deletes the whole dist/ directory then it makes it hard to have compiled the Setup.hs and kept the compiled binary under dist/. In this situation we want some cooperation between. See #296.
• runghc Setup.hs install/register this is a handy "do everything" command but it's annoying for build scripts because it registers now locally. It's essential for distributions to be able to register later and to control that themselves.

In fact both sdist and clean are examples of commands that are not strictly necessary to building a package from a tarball. They are however rather useful features of a build system that developers can use. Perhaps what we want to do is split the command line interface into various levels, from most basic to more sophisticated. This would allow a minimal Setup.hs that can be used by another tool but itself is not very user friendly.

A tension between an interface designed for people and for tools is that tools want more control over the environment while people want commands that just work. Tools want to do things like controlling what ghc version is used, what ghc package databases are looked at, what versions of what tools are used etc.

Every feature that we require of packages adds extra requirements to the build system. For example, people want to build relocatable packages. Many users appreciate being able to specify where build files go and rely on files only being written into that directory. However these are all additional constraints and burdens on build systems. How do we strike a balance, or how do we allow many levels of functionality. How are higher layer tools able to detect what features the build system for a particular package supports?

Minimal Setup.hs interface

This is a interface for tools not humans. It is the minimum needed by tools like cabal-install or distro package builders. It is not suitable as a developer build system, only distribution.

Setup.hs configure --prefix= --package-db=
Setup.hs build
Setup.hs copy --destdir=
Setup.hs register --pkg-info=

Compared to the original proposal this abolishes --global, --user. These are

TODO: what about other control over the environment:

GHC_PACKAGE_PATH ?
CC_OPTIONS ?
--package-db=
--with-prog=
--prog-option=