Module signature

A module signature is a type signature for a module. Similar to hs-boot files, module signatures contain only type definitions and type signatures, and do not have any value bindings:

signature Str where

data Str
empty :: Str
append :: Str -> Str -> Str

A package may define signatures in lieu of modules (e.g., as in str-sig); clients of these packages must provide implementations of the modules specified by these signatures before being able to compile and run these packages.

Signatures are part of Backpack, a new facility for modular programming in GHC; here, they are used to defer the choice of an implementation of a module to a user. These features are only compatible with GHC 8.2, and currently are only allowed in packages uploaded to next.hackage, an experimental staging ground for packages that use these new facilities.

In the rest of this page, we'll give some guidance for how to make use of these features if you are on GHC 8.2.

For the impatient

There's a package on Hackage, you want to use it, but it has some signatures and you're not sure what to do (we call this an indefinite package). Here is what you should do:

1. Does the package define any modules? Pure signature packages like str-sig don't define any modules, meaning that they are purely intended for developers who want to use this signature to parametrize their own packages. If you are actually interested in using signatures to parametrize your package, skip to the next session; the quick start won't help you.
2. Find out if the package author has defined any pre-instantiated packages which have the implementations at the types you want; usually, they should be linked from the package description in question. For example, if you are looking at the simple-regex-indef package, and you want to use the regular expressions on strings, check and see if there is a simple-regex-string package. (TODO: link the example) If so, you can directly depend on that package and ignore the existence of Backpack (just remember that you need to be running GHC 8.2 or later.)
3. If the author has not defined a pre-instantiated package, you may be able to instantiate it yourself. First, you have to find a package which provides implementations of the signatures in question; if the package depends on a signature package, you can probably click to that package to find out what valid implementations of that signature are available. Then, you will need to instantiate the package. This is done by depending on both the indefinite package and the implementing package, e.g., build-depends: simple-regex-indef, str-string: this will instantiate simple-regex-indef with whatever implementing module str-string brings into scope under the name Str; if you want to use a differently named module, use the mixins field to rename the module you want to the signature name, e.g., mixins: str-bytestring (Str.ByteString.Lazy as Str)
4. If you do all that, but GHC complains that the signature requires a function/type which is not defined by the module, this means that the implementing module doesn't implement enough functionality to support the requirements of the package in question. You might be able to extend module with the missing functionality, see more below.