Structure of a Haskell project

The intention behind this page is to flesh out some semi-standard for the directory structure, and the tool-setup for medium to large-sized Haskell projects. It is intended to make it easier for newcomers to start up projects, and for everybody to navigate others projects. Newcomers should also read How to write a Haskell program for more detailed instructions on setting up a new project.

Especially I hope some focus can be made on how to make the different tools play well together, and giving the project structure that allows scaling.

Hopefully someone more qualified than I (the initiator of this page) will be summoned and write their advices, change the faults, add missing bits and discuss differences in opinions.

And perhaps a sample project (in the spirit of HNop, but with broader ambitions) should be made, so that can be used as a template.

Tools

It is recommended to make use of the following tool chain:

• Darcs for revision control
• Cabal for managing builds, tests and haddock'ing
• QuickCheck and SmallCheck for auto-generated test-cases
• HUnit for hand-coded tests
• Haddock for generating API documents or Literate programming combined with latex for thorough documentation of the code

Directory Structure

For a project called app an outline the directory structure should look like this (inspired by looking at projects like GHC, PUGS, Yi, Haskore, Hmp3, Fps):

app/             -- Root-dir
  src/           -- For keeping the sourcecode
    Main.lhs     -- The main-module
    App/         -- Use hierarchical modules
      ...
      Win32/     -- For system dependent stuff
      Unix/
    cbits/       -- For C code to be linked to the haskell program
  testsuite/     -- Contains the testing stuff
    runtests.sh  -- Will run all tests
    tests/       -- For unit-testing and checking
      App/       -- Clone the module hierarchy, so that there is one 
                    testfile per sourcefile
    benchmarks/   -- For testing performance
  doc/           -- Contains the manual, and other documentation
    examples/    -- Example inputs for the program
    dev/         -- Information for new developers about the project, 
                    and eg. related literature
  util/          -- Auxiliary scripts for various tasks
  dist/          -- Directory containing what end-users should get
    build/       -- Contains binary files, created by cabal
    doc/         -- The haddock documentation goes here, created by cabal
    resources/   -- Images, soundfiles and other non-source stuff
                    used by the program
  _DARCS/        
  README         -- Textfile with short introduction of the project
  INSTALL        -- Textfile describing how to build and install
  TODO           -- Textfile describing things that ought to be done
  AUTHORS        -- Textfile containing info on who does and has done 
                    what in this project, and their contact info
  LICENSE        -- Textfile describing licensing terms for this project
  app.cabal      -- Project-description-file for cabal
  Setup.hs       -- Program for running cabal commands

Technicalities

The sourcefiles

• It is recommended to write sourcefiles in plain ascii or UTF-8 with unix line-endings using only spaces (and not tabs) for indentation.
• The interface (everything a module exports) should be commented in english with haddock comments.
• All of the code should be a large latex document going through the code and explaining it. The latex markup should be kept light, so that it is still readable in an editor. The main module should include all of the files somehow.
• The modules should have explicit export-lists.
• Explicit type-annotations should be given for all top-level definitions.

Discussions

Why not use lhs2Tex

Some short experiments showed that lhs2Tex is not too happy about haddock-comments, and since these two techniques of commenting are orthogonal something else should be chosen. Eg. latex.sty

How is the testing framework best made?

Here should be a recipe for making a test-framework with both HUnit-tests and QuickCheck properties, that can all be run with a simple command, and how to make darcs use that for testing before recording.

HTF attempts to be such a test-framework, but is currently woefully under documented (although there's a tutorial hidden in the documentation for Test.Framework.Tutorial).

Alternatively, test-framework has a similiar function as HTF.

Additional testing frameworks.

Blog Posts and other External discussions

Michael Snoyman on project template for Haskell.