Structure of a Haskell project
(moderate recommendation of .lhs. Its rarely used in practice)
(Additional section for blog posts and more recent discussions.)
|(10 intermediate revisions by 8 users not shown)|
Latest revision as of 05:53, 12 December 2012
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.
 1 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
 2 Directory Structure
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 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.
 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 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.
 4.3 Blog Posts and other External discussions
Michael Snoyman on project template for Haskell.