Revision control

Use darcs, unless you have a specific reason not to, in which case use git. If you don't like git, go back and look at darcs. It's written in Haskell, and it's used by many Haskell developers. See the wikibook Understanding darcs to get started.

Build system

Use Cabal. You should read at least the start of section 2 of the Cabal User's Guide.

Documentation

For libraries, use Haddock. We recommend using recent versions of haddock (2.8 or above, as of December 2010).

Testing

Pure code can be tested using QuickCheck or SmallCheck, impure code with HUnit.

To get started, try Haskell/Testing. For a slightly more advanced introduction, Simple Unit Testing in Haskell is a blog article about creating a testing framework for QuickCheck using some Template Haskell.

Create a directory

Create somewhere for the source:

$ mkdir haq
$ cd haq

Write some Haskell source

Write your program:

$ cat > Haq.hs
--
-- Copyright (c) 2006 Don Stewart - http://www.cse.unsw.edu.au/~dons
-- GPL version 2 or later (see http://www.gnu.org/copyleft/gpl.html)
--
import System.Environment

-- 'main' runs the main program
main :: IO ()
main = getArgs >>= print . haqify . head

haqify s = "Haq! " ++ s

Stick it in darcs

Place the source under revision control:

$ darcs init
$ darcs add Haq.hs 
$ darcs record
addfile ./Haq.hs
Shall I record this change? (1/?)  [ynWsfqadjkc], or ? for help: y
hunk ./Haq.hs 1
+--
+-- Copyright (c) 2006 Don Stewart - http://www.cse.unsw.edu.au/~dons
+-- GPL version 2 or later (see http://www.gnu.org/copyleft/gpl.html)
+--
+import System.Environment
+
+-- | 'main' runs the main program
+main :: IO ()
+main = getArgs >>= print . haqify . head
+
+haqify s = "Haq! " ++ s
Shall I record this change? (2/?)  [ynWsfqadjkc], or ? for help: y
What is the patch name? Import haq source
Do you want to add a long comment? [yn]n
Finished recording patch 'Import haq source'

And we can see that darcs is now running the show:

$ ls
Haq.hs _darcs

For git:

$ git config --global user.name "John Doe"
$ git config --global user.email johndoe@example.com
$ git init
$ git add *
$ git commit -m 'Import haq source'
$ ls -A
.git Haq.hs

Add a build system

Create a .cabal file describing how to build your project:

$ cat > haq.cabal
Name:                haq
Version:             0.0
Synopsis:            Super cool mega lambdas
Description:         My super cool, indeed, even mega lambdas 
                     will demonstrate a basic project. You will marvel.
License:             GPL
License-file:        LICENSE
Author:              Don Stewart
Maintainer:          Don Stewart <dons@cse.unsw.edu.au>
Build-Depends:       base

Executable:          haq
Main-is:             Haq.hs

(If your package uses other packages, e.g. array, you'll need to add them to the Build-Depends: field.) Add a Setup.lhs that will actually do the building:

$ cat > Setup.lhs
#! /usr/bin/env runhaskell

> import Distribution.Simple
> main = defaultMain

Cabal allows either Setup.hs or Setup.lhs; as long as the format is appropriate, it doesn't matter which one you choose. But it's a good idea to always include the #! /usr/bin/env runhaskell line; because it follows the shebang convention, you could execute the Setup.hs directly in a Unix shell instead of always manually calling runhaskell (assuming the Setup file is marked executable, of course).

Record your changes:

$ darcs add haq.cabal Setup.lhs
$ darcs record --all
What is the patch name? Add a build system
Do you want to add a long comment? [yn]n
Finished recording patch 'Add a build system'

Git:

$ git add haq.cabal Setup.lhs
$ git commit -m 'Add a build system'

Build your project

Now build it!

$ runhaskell Setup.lhs configure --prefix=$HOME --user
$ runhaskell Setup.lhs build
$ runhaskell Setup.lhs install

Run it

And now you can run your cool project:

$ haq me
"Haq! me"

You can also run it in-place, avoiding the install phase:

$ dist/build/haq/haq you
"Haq! you"

Build some haddock documentation

Generate some API documentation into dist/doc/*

$ runhaskell Setup.lhs haddock

which generates files in dist/doc/ including:

$ w3m -dump dist/doc/html/haq/Main.html
 haq Contents Index
 Main

 Synopsis
 main :: IO ()

 Documentation

 main :: IO ()
 main runs the main program

 Produced by Haddock version 0.7

No output? Make sure you have actually installed haddock. It is a separate program, not something that comes with the Haskell compiler, like Cabal.

Add some automated testing: QuickCheck

We'll use QuickCheck to specify a simple property of our Haq.hs code. Create a tests module, Tests.hs, with some QuickCheck boilerplate:

$ cat > Tests.hs
import Char
import List
import Test.QuickCheck
import Text.Printf

main  = mapM_ (\(s,a) -> printf "%-25s: " s >> a) tests

instance Arbitrary Char where
    arbitrary     = choose ('\0', '\128')
    coarbitrary c = variant (ord c `rem` 4)

Now let's write a simple property:

$ cat >> Tests.hs 
-- reversing twice a finite list, is the same as identity
prop_reversereverse s = (reverse . reverse) s == id s
    where _ = s :: [Int]

-- and add this to the tests list
tests  = [("reverse.reverse/id", test prop_reversereverse)]

We can now run this test, and have QuickCheck generate the test data:

$ runhaskell Tests.hs
reverse.reverse/id       : OK, passed 100 tests.

Let's add a test for the 'haqify' function:

-- Dropping the "Haq! " string is the same as identity
prop_haq s = drop (length "Haq! ") (haqify s) == id s
    where haqify s = "Haq! " ++ s

tests  = [("reverse.reverse/id", test prop_reversereverse)
        ,("drop.haq/id",        test prop_haq)]

and let's test that:

$ runhaskell Tests.hs
reverse.reverse/id       : OK, passed 100 tests.
drop.haq/id              : OK, passed 100 tests.

Great!

Running the test suite from darcs

We can arrange for darcs to run the test suite on every commit:

$ darcs setpref test "runhaskell Tests.hs"
Changing value of test from '' to 'runhaskell Tests.hs'

will run the full set of QuickChecks. (If your test requires it you may need to ensure other things are built too e.g.: darcs setpref test "alex Tokens.x;happy Grammar.y;runhaskell Tests.hs").

Let's commit a new patch:

$ darcs add Tests.hs
$ darcs record --all
What is the patch name? Add testsuite
Do you want to add a long comment? [yn]n
Running test...
reverse.reverse/id       : OK, passed 100 tests.
drop.haq/id              : OK, passed 100 tests.
Test ran successfully.
Looks like a good patch.
Finished recording patch 'Add testsuite'

Excellent, now patches must pass the test suite before they can be committed.

Tag the stable version, create a tarball, and sell it!

Tag the stable version:

$ darcs tag
What is the version name? 0.0
Finished tagging patch 'TAG 0.0'

$ darcs dist -d haq-0.0
Created dist as haq-0.0.tar.gz

$ runhaskell Setup.lhs sdist
Building source dist for haq-0.0...
Source tarball created: dist/haq-0.0.tar.gz

extra-source-files: Tests.hs

data-files: AUTHORS, README

Summary

The following files were created:

   $ ls
   Haq.hs           Tests.hs         dist             haq.cabal
   Setup.lhs        _darcs           haq-0.0.tar.gz

Hierarchical source

The source should live under a directory path that fits into the existing module layout guide. So we would create the following directory structure, for the module Data.LTree:

   $ mkdir Data
   $ cat > Data/LTree.hs 
   module Data.LTree where

So our Data.LTree module lives in Data/LTree.hs

The Cabal file

Cabal files for libraries list the publicly visible modules, and have no executable section:

   $ cat ltree.cabal 
   Name:                ltree
   Version:             0.1
   Description:         Lambda tree implementation
   License:             BSD3
   License-file:        LICENSE
   Author:              Don Stewart
   Maintainer:          dons@cse.unsw.edu.au
   Build-Depends:       base
   Exposed-modules:     Data.LTree

We can thus build our library:

   $ runhaskell Setup.lhs configure --prefix=$HOME --user
   $ runhaskell Setup.lhs build    
   Preprocessing library ltree-0.1...
   Building ltree-0.1...
   [1 of 1] Compiling Data.LTree       ( Data/LTree.hs, dist/build/Data/LTree.o )
   /usr/bin/ar: creating dist/build/libHSltree-0.1.a

and our library has been created as a object archive. On *nix systems, you should probably add the --user flag to the configure step (this means you want to update your local package database during installation). Now install it:

   $ runhaskell Setup.lhs install
   Installing: /home/dons/lib/ltree-0.1/ghc-6.6 & /home/dons/bin ltree-0.1...
   Registering ltree-0.1...
   Reading package info from ".installed-pkg-config" ... done.
   Saving old package config file... done.
   Writing new package config file... done.

And we're done! You can use your new library from, for example, ghci:

   $ ghci -package ltree
   Prelude> :m + Data.LTree
   Prelude Data.LTree> 

The new library is in scope, and ready to go.

More complex build systems

For larger projects it is useful to have source trees stored in subdirectories. This can be done simply by creating a directory, for example, "src", into which you will put your src tree.

To have Cabal find this code, you add the following line to your Cabal file:

   hs-source-dirs: src

Cabal can set up to also run configure scripts, along with a range of other features. For more information consult the Cabal documentation.

   other-modules: My.Own.Module

cabal init

A package management tool for Haskell called cabal-install provides a command line tool to help developers create a simple cabal project. Just run and answer all the questions. Default values are provided for each.

$ cabal init
Package name [default "test"]? 
Package version [default "0.1"]? 
Please choose a license:
...

mkcabal

mkcabal is a tool that existed before cabal init, which also automatically populates a new cabal project :

   darcs get http://code.haskell.org/~dons/code/mkcabal

N.B. This tool does not work in Windows. The Windows version of GHC does not include the readline package that this tool needs.

Usage is:

$ mkcabal
Project name: haq
What license ["GPL","LGPL","BSD3","BSD4","PublicDomain","AllRightsReserved"] ["BSD3"]: 
What kind of project [Executable,Library] [Executable]: 
Is this your name? - "Don Stewart " [Y/n]: 
Is this your email address? - "<dons@cse.unsw.edu.au>" [Y/n]: 
Created Setup.lhs and haq.cabal
$ ls
Haq.hs    LICENSE   Setup.lhs _darcs    dist      haq.cabal

which will fill out some stub Cabal files for the project 'haq'.

To create an entirely new project tree:

$ mkcabal --init-project
Project name: haq
What license ["GPL","LGPL","BSD3","BSD4","PublicDomain","AllRightsReserved"] ["BSD3"]: 
What kind of project [Executable,Library] [Executable]: 
Is this your name? - "Don Stewart " [Y/n]: 
Is this your email address? - "<dons@cse.unsw.edu.au>" [Y/n]: 
Created new project directory: haq
$ cd haq
$ ls
Haq.hs    LICENSE   README    Setup.lhs haq.cabal