Personal tools

How to write a Haskell program

From HaskellWiki

Revision as of 20:11, 24 November 2006 by Benmos (Talk | contribs)

Jump to: navigation, search

A guide to the best practice for creating a new Haskell project or program.

Contents

1 Recommended tools

Almost all new Haskell projects use the following tools. Each is intrinsically useful, but using a set of common tools also benefits everyone by increasing productivity, and you're more likely to get patches.

1.1 Revision control

Use Darcs unless you have a specific reason not to. It's much more powerful than most competing systems (and it's written in Haskell).

1.2 Build system

Use Cabal. You should read at least the start of section 2 of the Cabal User's Guide. We recommend writing the setup script as a file called Setup.lhs with these contents:

#! /usr/bin/env runhaskell
 
> import Distribution.Simple
> main = defaultMain

Writing the setup file this way allows it to be executed directly by Unix shells.

1.3 Documentation

For libraries, use Haddock.

1.4 Testing

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

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

2 Structure of a simple project

The basic structure of a new Haskell project can be adopted from HNop, the minimal Haskell project. It consists of the following files, for the mythical project "haq".

  • Haq.hs -- the main haskell source file
  • haq.cabal -- the cabal build description
  • Setup.hs -- build script itself
  • _darcs -- revision control
  • README -- info
  • LICENSE -- license

You can of course elaborate on this, with subdirectories and multiple modules.

Here is a transcript on how you'd create a minimal darcs and cabalised Haskell project, for the cool new Haskell program "haq", build it, install it and release.

The new tool 'mkcabal' automates all this for you, but its important to understand all the parts first.

2.1 Create a directory

Create somewhere for the source:

$ mkdir haq
$ cd haq

2.2 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

2.3 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

2.4 Add a build system

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

$ cat > haq.cabal
Name:                haq
Version:             0.0
Description:         Super cool mega lambdas
License:             GPL
License-file:        LICENSE
Author:              Don Stewart
Maintainer:          dons@cse.unsw.edu.au
Build-Depends:       base
 
Executable:          haq
Main-is:             Haq.hs
ghc-options:         -O

(If your package uses other packages, e.g. haskell98, 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

And 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'

2.5 Build your project

Now build it!

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

2.6 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"

2.7 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

2.8 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!

2.9 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 eg: 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.

2.10 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'

Now generate a tarball:

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

And you're all set up!

2.11 Summary

The following files were created:

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

3 Automation

A tool to automatically populate a new cabal project is available (beta!):

   darcs get http://www.cse.unsw.edu.au/~dons/code/mkcabal

Usage is:

    $ runhaskell mkcabal.hs
    Project name: haq
    Created Setup.hs and haq.cabal

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

To create an entire project tree:

    $ runhaskell mkcabal.hs --init-project
    Project name: ruby-on-rails-killer
    Created new project directory: ruby-on-rails-killer
 
    $ ls ruby-on-rails-killer
    LICENSE
    Ruby-on-rails-killer.hs
    ruby-on-rails-killer.cabal
    README
    Setup.hs

4 Licenses

Code for the common base library package must be BSD licensed. Otherwise, it is entirely up to you as the author. Choose a licence (inspired by this). Check the licences of things you use, both other Haskell packages and C libraries, since these may impose conditions you must follow. Use the same licence as related projects, where possible. The Haskell community is split into 2 camps, roughly, those who release everything under BSD, and (L)GPLers. Some Haskellers recommend avoiding LGPL, due to cross module optimisation issues. Like many licensing questions, this advice is controversial. Several Haskell projects (wxHaskell, HaXml, etc) use the LGPL with an extra permissive clause which gets round the cross-module optimisation thing.

5 Releases

It's important to release your code as stable, tagged tarballs. Don't just rely on darcs for distribution.

  • darcs dist generates tarballs directly from a darcs repository

For example:

$ cd fps
$ ls       
Data      LICENSE   README    Setup.hs  TODO      _darcs    cbits dist      fps.cabal tests
$ darcs dist -d fps-0.8
Created dist as fps-0.8.tar.gz

You can now just post your fps-0.8.tar.gz

You can also have darcs do the equivalent of 'daily snapshots' for you by using a post-hook.

put the following in _darcs/prefs/defaults:

 apply posthook darcs dist
 apply run-posthook

Advice:

  • Tag each release

6 Hosting

A Darcs repository can be published simply by making it available from a web page. If you don't have an account online, or prefer not to do this yourself, source can be hosted on darcs.haskell.org (you will need to email Simon Marlow to do this). haskell.org itself has some user accounts available.

There are also many free hosting places for open source, such as

7 Web page

Create a web page documenting your project! An easy way to do this is to add a project specific page to the Haskell wiki

8 Program structure

Monad transformers are very useful for programming in the large, encapsulating state, and controlling side effects. To learn more about this approach, try Monad Transformers Step by Step.

9 Publicity

The best code in the world is meaningless if nobody knows about it:

  • Firstly, join the community! Subscribe to at least haskell-cafe@ and haskell@ mailing lists.
  • Announce your project releases to haskell@haskell.org! This ensure it will then make it into the Haskell Weekly News. To be doubly sure, you should CC the release to the HWN editor
  • Blog about it, on Planet Haskell
    • Write about it on your blog
    • Then email the Planet Haskell maintainer (ibid on #haskell) the RSS feed url for your blog
  • Add your library or tool to the Libraries and tools page, under the relevant category, so people can find it.