Personal tools

Structure of a Haskell project

From HaskellWiki

(Difference between revisions)
Jump to: navigation, search
(Additional section for blog posts and more recent discussions.)
 
(6 intermediate revisions by 5 users not shown)
Line 18: Line 18:
   
 
== Tools ==
 
== Tools ==
It is recommended to make use the following tool chain:
+
It is recommended to make use of the following tool chain:
 
* [[Darcs]] for revision control
 
* [[Darcs]] for revision control
 
* [[Cabal]] for managing builds, tests and haddock'ing
 
* [[Cabal]] for managing builds, tests and haddock'ing
Line 28: Line 28:
   
 
For a project called app an outline the directory structure should
 
For a project called app an outline the directory structure should
look like this (inspired by looking at projects like GHC, PUGS, Yi,
+
look like this (inspired by looking at projects like [[GHC]], PUGS, Yi,
Haskore, Hmp3, Fps):
+
[[Haskore]], Hmp3, Fps):
   
 
<pre>
 
<pre>
Line 72: Line 72:
 
* It is recommended to write sourcefiles in plain ascii or UTF-8 with unix line-endings using only spaces (and not tabs) for indentation.
 
* 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.
 
* 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.
+
* 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
+
* The modules should have explicit export-lists.
 
* Explicit type-annotations should be given for all top-level definitions.
 
* Explicit type-annotations should be given for all top-level definitions.
   
Line 81: Line 81:
 
Some short experiments showed that lhs2Tex is not too happy about
 
Some short experiments showed that lhs2Tex is not too happy about
 
haddock-comments, and since these two techniques of commenting are
 
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]]
+
orthogonal something else should be chosen. Eg. [http://www.acooke.org/jara/pancito/haskell.sty latex.sty]
   
 
=== How is the testing framework best made? ===
 
=== How is the testing framework best made? ===
   
 
Here should be a recipe for making a test-framework with both
 
Here should be a recipe for making a test-framework with both
HUnit-tests an QuickCheck properties, that can all be run with a
+
HUnit-tests and QuickCheck properties, that can all be run with a
 
simple command, and how to make darcs use that for testing before
 
simple command, and how to make darcs use that for testing before
 
recording.
 
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.
+
[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.]

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.

Contents

[edit] 1 Tools

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

[edit] 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

[edit] 3 Technicalities

[edit] 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.

[edit] 4 Discussions

[edit] 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

[edit] 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.

Additional testing frameworks.

[edit] 4.3 Blog Posts and other External discussions

Michael Snoyman on project template for Haskell.