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://darcs.haskell.org.
Make distribution tarballs and install on server.
Automated download and build in a fresh local temp directory for testing.
Copy Haddock docs to server
Generate editor tags files (via hasktags).
Convert source files between dos-style and unix-style line endings.
Customizable.

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 TV as follows:

user = conal
configure-dirs=--prefix=c:/Haskell/packages --datadir=c:/Haskell/packages
haddock_interfaces=\
  http://haskell.org/ghc/docs/latest/html/libraries/base,c:/ghc/ghc-6.6/doc/html/libraries/base/base.haddock \
  http://haskell.org/ghc/docs/latest/html/libraries/mtl,c:/ghc/ghc-6.6/doc/html/libraries/mtl/mtl.haddock \
  http://darcs.haskell.org/packages/DeepArrow/doc/html,c:/Haskell/packages/DeepArrow-0.0.1/doc/html/DeepArrow.haddock

include c:/Haskell/cabal-make/cabal-make.inc

I don't like wiring the interface paths (especially with version numbers) into my makefile, but I don't know how to avoid it. Suggestions, please.

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

Darcs-related targets:

darcs-repo: makes a repository at http://darcs.haskell.org/packages/TV
darcs-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 TV Makefile is really

haddock_interfaces=\
  http://haskell.org/ghc/docs/latest/html/libraries/base,c:/ghc/ghc-6.6/doc/html/libraries/base/base.haddock \
  http://haskell.org/ghc/docs/latest/html/libraries/mtl,c:/ghc/ghc-6.6/doc/html/libraries/mtl/mtl.haddock \
  http://darcs.haskell.org/packages/DeepArrow/doc/html,c:/Haskell/packages/DeepArrow-0.0.1/doc/html/DeepArrow.haddock

include ../my-cabal-make.inc

Dependencies

Recent Cabal (1.1.8 or better, or get the latest from Cabal darcs repo)
Recent Haddock (0.8.1 or better, or latest from Haddock darcs repo)
Recent hscolour (1.7 or newer, or latest from hscolour darcs repo)
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.

Get it

darcs get --partial http://darcs.haskell.org/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 hard-wiring the interface paths into my makefile.
Eliminate the restrictions/assumptions listed in #Use guidelines.