Difference between revisions of "Cabal-make"

Revision as of 02:30, 17 February 2007

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-project, 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 a 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.9 or better, or latest from Haddock darcs repo)
GNU make

Get it

darcs get 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.