Cabal-make

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.