Cabal-make

The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Abstract

Cabal-make is an include file for GNU make files to be used with Cabal in sharing Haskell packages. It is intended mainly for package authors. People who just build & install packages software can do so entirely with Cabal commands. In particular, it's a bit hairy to get the best results from Haddock & hscolour.

Features

Web-based, cross-package links in Haddock docs (documentation generated by Haddock).
Syntax coloring via hscolour, with per-project CSS.
Links from the Haddock docs to hscolour'd code (per-module, and per-entity).
Links from Haddock docs to wiki-based user comment pages (per-project and per-module), with automatic subscription (for email notification).
Set up with darcs repositories on http://code.haskell.org or elsewhere.
Make distribution tarballs and install on server.
Automated download and build in a fresh local temp directory for testing.
Copy Haddock docs to server (deprecated now that hackage has caught up with ghc).
Generate editor tags files (via hasktags).
Convert source files between dos-style and unix-style line endings.
Customizable.

Packages using cabal-make

To get a concrete sense of the first few of the features listed above, here are some links to docs for packages that use cabal-make. (Please add your own packages to this list when you use cabal-make.)

Phooey: a simple, arrow-based functional GUI library
DeepArrow: a framework for composable semantic editors
TV: combined and separable packaging of functionality and interface
GuiTV: GUIs for TV
Checkers: Some QuickCheck helpers
FieldTrip: Functional 3D
Reactive: Functional reactive programming with a data-driven implementation

Example use

On my Windows system, I've placed cabal-make at c:\Haskell\cabal-make, and I like to install Haskell packages under c:\Haskell\packages. I might write a Makefile for the package checkers as follows:

user = conal
cabal-make = c:/conal/Haskell/cabal-make
configure-dirs = --prefix=c:/Haskell/packages --datadir=c:/Haskell/packages --libdir=c:/Haskell/packages --bindir=c:/Haskell/packages/bin
hscolour-css = $(cabal-make)/hscolour.css

server = code.haskell.org
server-dir = /srv/code
server-url-dir =
include ../my-cabal-make.inc

To build checkers, I run "make" with targets like "configure", "build", "doc", and "install". Or "all" (default) for all of these targets.

A few darcs-related targets:

pull and push.
repo: makes a remote repository
tag: do "darcs tag" using current version (extracted from project Cabal file)
darcs-dist: make a tarball and copy to server.
web-doc: copy docs & colored sources to the server.
test-get-build: Test by doing "darcs get", configure, and build in a fresh temp directory.

The target "watch-comments" sets up a subscription to the Haskell wiki talk pages that correspond to the package's modules (for the user comment links inserted in the Haddock docs.)

There are a few other targets as well. See the source.

Specializing

I use a trick for collecting my favorite setting to be saved across my own packages. The file is called "my-cabal-make.inc":

user = conal
cabal-make = c:/Haskell/cabal-make
configure-dirs = --prefix=c:/Haskell/packages --datadir=c:/Haskell/packages
hscolour-css = $(cabal-make)/hscolour.css

include $(cabal-make)/cabal-make.inc

Then I just have to define haddock_interfaces and include my-cabal-make. My checkers Makefile is really

user = conal
cabal-make = c:/Haskell/cabal-make
configure-dirs = --prefix=c:/Haskell/packages --datadir=c:/Haskell/packages
hscolour-css = $(cabal-make)/hscolour.css

include $(cabal-make)/cabal-make.inc

Dependencies

Cabal
darcs for push & pull targets
Haddock and hscolour if you make your own docs
GNU make

Use guidelines

In order for cabal-make to work, you have to list each of your source modules on a line by itself, including the first one in the list (instead of placing it aside the Cabal directive). You can use "make show-modules" to see if your list of source modules is extracted correctly.
Cabal-make assumes your source code to be under src. Overridable via top-src-dir.

Get it

darcs get --partial http://code.haskell.org/~conal/code/cabal-make

Customization

There are several customization variables defined in cabal-make that can be overriden. Simply define these variables in your makefile before "cabal-make.inc". See the "Settings" section of the source.

To do

Eliminate the restrictions/assumptions listed in #Use guidelines.