View source for Structure of a Haskell project

[[Category:Applications]]
[[Category: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.

== 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):

<pre>
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
</pre>

== 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. [http://www.acooke.org/jara/pancito/haskell.sty 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.

[http://www.informatik.uni-freiburg.de/~wehr/software/haskell/#HTF_-_The_Haskell_Test_Framework 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, [http://batterseapower.github.com/test-framework/ test-framework] has a similiar function as HTF.

[[Development_Libraries_and_Tools#Testing_Frameworks| Additional testing frameworks.]]

===Blog Posts and other External discussions===

Michael Snoyman on project [http://www.yesodweb.com/blog/2012/09/project-templates template for Haskell.]