# Haskell/Packaging

* Packaging
* General Practices
* Debugging
* Testing
* Packaging your software (Cabal)
* Using the Foreign Function Interface (FFI)
* Generic programming: Scrap your boilerplate
A guide to the best practice for creating a new Haskell project or program.

## Recommended tools

Almost all new Haskell projects use the following tools. Each is intrinsically useful, but using a set of common tools also benefits everyone by increasing productivity, and you're more likely to get patches.

### Build system

Use Cabal. You should read the Cabal User's Guide. Particularly, section two and also section three will be very helpful. For generating a project, Cabal depends on Git, so we recommend installing it if you don't have it already.

### Documentation

For libraries, use Haddock.

### Testing

Pure code can be tested using QuickCheck (for tasty integration, which is recommended, tasty-quickcheck), hedgehog, or SmallCheck (though as of 2023 they recommend using falsify instead with tasty), and impure code can be tested with tasty-hunit.
To get started, try Haskell/Testing. For a slightly more advanced introduction, Simple Unit Testing in Haskell is a blog article about creating a testing framework for QuickCheck using some Template Haskell.

## Structure of a simple project

You can generate a new Haskell project using `cabal init`. It will interactively ask you a few questions by default to help set your project up. For most of the questions, the default are fine.
If you disable the interactive mode though, it will not ask you the questions. Assume that $DIR is the name of the current directory. It'll generate a project with this shape:
* app/Main.hs -- the main haskell source file
* $DIR.cabal -- the cabal build description
* CHANGELOG.md
You can of course modify this, with subdirectories and multiple modules.
Here is a transcript on how you'd create a minimal Haskell project using Git and Cabal build it, install it and release.
The command tool 'cabal init' automates all this for you, but it's important that you understand all the parts first.
We will now walk through the creation of the infrastructure for a simple Haskell executable. Advice for libraries follows after.

### Create a directory

Create a directory for the source:

## Generate a project skeleton using Cabal

First, run cabal update to update cabal's repositories.
As directed earlier, run cabal init and answer the question with what you see fit.
For most of these you can just pick your own, but as we pointed out earlier, the defaults are fine. For the question about choosing a language, you should pick the latest existing language if possible.
If your package uses other packages, e.g. array, you'll need to add them to the Build-Depends: field of the Cabal file.

### Write some Haskell source

Write your program:

## Stick it in Git
### Build your project

Now build it!

### Run it

And now you can run your cool project:

### Build some haddock documentation

Generate some API documentation into dist/doc/*
Which will tell you where the documentation is generated. You can view it via
No output? Make sure you have actually installed haddock.

### Add some automated testing: QuickCheck

We'll use QuickCheck to specify a simple property of our Haq.hs code. Create a tests module, Tests.hs, with some QuickCheck boilerplate:
Now let's write a simple property:
We can now run this test, and have QuickCheck generate the test data:
Let's add a test for the 'haqify' function:
and let's test that:
Great!

### Running the test suite from darcs

We can arrange for darcs to run the test suite on every commit:
will run the full set of QuickChecks. (If your test requires it you may need to ensure other things are built too e.g.: darcs setpref test "alex Tokens.x;happy Grammar.y;runhaskell Tests.hs").
Let's commit a new patch:
Excellent, now patches must pass the test suite before they can be committed.

### Tag the stable version, create a tarball, and sell it!

Tag the stable version:

#### Advanced Darcs functionality: lazy get

As your repositories accumulate patches, new users can become annoyed at how long it takes to accomplish the initial darcs get. (Some projects, like yi or GHC, can have thousands of patches.) Darcs is quick enough, but downloading thousands of individual patches can still take a while. Isn't there some way to make things more efficient?
Darcs provides the --lazy option to darcs get. This enables to download only the latest version of the repository. Patches are later downloaded on demand if needed.

#### Distribution

When distributing your Haskell program, you have roughly three options:
* distributing via a Darcs repository
* distributing a tarball
** a Darcs tarball
** a Cabal tarball
With a Darcs repository, if it is public, then you are done. However: perhaps you don't have a server with Darcs, or perhaps your computer isn't set up for people to darcs pull from it. In which case you'll need to distribute the source via tarball.

##### Tarballs via darcs

Darcs provides a command where it will make a compressed tarball, and it will place a copy of all the files it manages into it. (Note that nothing in _darcs will be included - it'll just be your source files, no revision history.)
And you're all set up!

##### Tarballs via Cabal

Since our code is cabalised, we can create a tarball with Cabal directly:
This has advantages and disadvantages compared to a Darcs-produced tarball. The primary advantage is that Cabal will do more checking of our repository, and more importantly, it'll ensure that the tarball has the structure needed by HackageDB and cabal-install.
However, it does have a disadvantage: it packages up only the files needed to build the project. It will deliberately fail to include other files in the repository, even if they turn out to be necessary at some point. To include other files (such as Test.hs in the above example), we need to add lines to the cabal file like:
If we had them, we could make sure files like AUTHORS or the README get included as well:

### Summary

The following files were created:

## Libraries

The process for creating a Haskell library is almost identical. The differences are as follows, for the hypothetical "ltree" library:

### Hierarchical source

The source should live under a directory path that fits into the existing module layout guide. So we would create the following directory structure, for the module Data.LTree:
So our Data.LTree module lives in Data/LTree.hs

### The Cabal file

Cabal files for libraries list the publicly visible modules, and have no executable section:
We can thus build our library:
and our library has been created as a object archive. On *nix systems, you should probably add the --user flag to the configure step (this means you want to update your local package database during installation). Now install it:
And we're done! You can use your new library from, for example, ghci:
The new library is in scope, and ready to go.

### More complex build systems

For larger projects it is useful to have source trees stored in subdirectories. This can be done simply by creating a directory, for example, "src", into which you will put your src tree.
To have Cabal find this code, you add the following line to your Cabal file:
Cabal can set up to also run configure scripts, along with a range of other features. For more information consult the Cabal documentation.

#### Internal modules

If your library uses internal modules that are not exposed, do not forget to list them in the other-modules field:
Failing to do so (as of GHC 6.8.3) may lead to your library deceptively building without errors but actually being unusable from applications, which would fail at build time with a linker error.

## Automation
### cabal init

A package management tool for Haskell called cabal-install provides a command line tool to help developers create a simple cabal project. Just run and answer all the questions. Default values are provided for each.

### mkcabal

mkcabal is a tool that existed before cabal init, which also automatically populates a new cabal project :
N.B. This tool does not work in Windows. The Windows version of GHC does not include the readline package that this tool needs.
Usage is:
which will fill out some stub Cabal files for the project 'haq'.
To create an entirely new project tree:

## Licenses

Code for the common base library package must be BSD licensed or something more Free/Open. Otherwise, it is entirely up to you as the author.
Choose a licence (inspired by this). Check the licences of things you use, both other Haskell packages and C libraries, since these may impose conditions you must follow.
Use the same licence as related projects, where possible. The Haskell community is split into 2 camps, roughly, those who release everything under BSD or public domain, and the GPL/LGPLers (this split roughly mirrors the copyleft/noncopyleft divide in Free software communities). Some Haskellers recommend specifically avoiding the LGPL, due to cross module optimisation issues. Like many licensing questions, this advice is controversial. Several Haskell projects (wxHaskell, HaXml, etc.) use the LGPL with an extra permissive clause to avoid the cross-module optimisation problem.

## Releases

It's important to release your code as stable, tagged tarballs. Don't just rely on darcs for distribution.
* darcs dist generates tarballs directly from a darcs repository
For example:
You can now just post your fps-0.8.tar.gz
You can also have darcs do the equivalent of 'daily snapshots' for you by using a post-hook.
put the following in _darcs/prefs/defaults:
Advice:
* Tag each release using darcs tag. For example:
Then people can darcs get --lazy --tag 0.8, to get just the tagged version (and not the entire history).

## Hosting

You can host public and private Darcs repositories on http://patch-tag.com/ for free. Otherwise, a Darcs repository can be published simply by making it available from a web page. Another option is to host on the Haskell Community Server at http://code.haskell.org/. You can request an account via http://community.haskell.org/admin/. You can also use https://github.com/ for Git hosting.

## Example

A complete example of writing, packaging and releasing a new Haskell library under this process has been documented.

## Notes

* ↑ This is actually a good thing, since it allows us to do things like create an elaborate test suite which doesn't get included in the tarball, so users aren't bothered by it. It also can reveal hidden assumptions and omissions in our code - perhaps your code was only building and running because of a file accidentally generated.
* Packaging
* General Practices
* Debugging
* >> Testing
* >> Packaging your software (Cabal)
* >> Using the Foreign Function Interface (FFI)
* >> Generic programming: Scrap your boilerplate
* Haskell
* Haskell Basics
* >> Elementary Haskell
* >> Intermediate Haskell
* >> Monads
* Advanced Haskell
* >> Fun with Types
* >> Wider Theory
* >> Haskell Performance
* Libraries Reference
* >> General Practices
* >> Specialised Tasks