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-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/TVdarcs-tag
: do "darcs tag
" using current version (extracted from project Cabal file)darcs-dist
: make a tarball and copy to serverweb-doc
: copy docs & colored sources to the servertest-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.