How to write a Haskell program

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

Structure

The basic structure of a new Haskell project can be adopted from HNop, the minimal Haskell project.

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.

Revision control

Use Darcs unless you have a specific reason not to. Almost all new Haskell projects are released under Darcs, and this benefits everyone -- a set of common tools increases productivity, and you're more likely to get patches.

Advice:

• Tag each release

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

And 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

Hosting

A Darcs repository can be publised 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

• Google Project Hosting
• SourceForge.

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

Build system

Use Cabal.

Example Setup

Create 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.

Example cabal file for Executables

Create the file myproject.cabal following this example:

Name:           MyProject
Version:        0.1
License:        BSD3
Author:         Your Name
Build-Depends:  base
Synopsis:       Example Cabal Executable File

Executable:     myproj
Main-Is:        Main.hs
Other-Modules:  Foo

Example cabal file for Libraries

Create the file myproject.cabal following this example:

Name:           MyProj
Version:        0.1
License:        BSD3
Author:         Your Name
Build-Depends:  base
Synopsis:       Example Cabal Library File
Exposed-Modules: MyProject.Foo

Documentation

Use Haddock.

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.

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.

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.