Structure of a Haskell project
Categories: Applications | Tutorials
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.
Contents |
1 Tools
It is recommended to make use 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
2 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
3 Technicalities
3.1 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 stil 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.
4 Discussions
4.1 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]
4.2 How is the testing framework best made?
Here should be a recipe for making a test-framework with both HUnit-tests an QuickCheck properties, that can all be run with a simple command, and how to make darcs use that for testing before recording.