Commit 96f9c1f4 authored by daniel's avatar daniel Committed by Mikhail Glushenkov
Browse files

Added documentation for Backpack-related fields.

parent 283030c0
......@@ -1115,6 +1115,22 @@ The library section should contain the following fields:
conflict (as would be the case with a stub module.) They can also be
used to resolve name conflicts.
.. pkg-field:: signatures: signature list
:since: 2.0
Supported only in GHC 8.2 and later. A list of `module signatures <>`__ required by this package.
Module signatures are part of the
`Backpack <>`__ extension to
the Haskell module system.
Packages that do not export any modules and only export required signatures
are called "signature-only packages", and their signatures are subjected to
`signature thinning
The library section may also contain build information fields (see the
section on `build information`_).
......@@ -2249,6 +2265,83 @@ system-dependent values for these fields.
On Darwin/MacOS X, a list of directories to search for frameworks.
This entry is ignored on all other platforms.
.. pkg-field:: mixins: mixin list
:since: 2.0
Supported only in GHC 8.2 and later. A list of packages mentioned in the
:pkg-field:`build-depends` field, each optionally accompanied by a list of
module and module signature renamings.
The simplest mixin syntax is simply the name of a package mentioned in the
:pkg-field:`build-depends` field. For example:
foo >= 1.2.3 && < 1.3
But this doesn't have any effect. More interesting is to use the mixin
entry to rename one or more modules from the package, like this:
foo (Foo.Bar as AnotherFoo.Bar, Foo.Baz as AnotherFoo.Baz)
There can be multiple mixin entries for a given package, in effect creating
multiple copies of the dependency:
foo (Foo.Bar as AnotherFoo.Bar, Foo.Baz as AnotherFoo.Baz),
foo (Foo.Bar as YetAnotherFoo.Bar)
The ``requires`` clause is used to rename the module signatures required by
a package:
foo (Foo.Bar as AnotherFoo.Bar) requires (Foo.SomeSig as AnotherFoo.SomeSig)
Signature-only packages don't have any modules, so only the signatures can
be renamed, with the following syntax:
sigonly requires (SigOnly.SomeSig as AnotherSigOnly.SomeSig)
See the :pkg-field:`signatures` field for more details.
Mixin packages are part of the `Backpack
<>`__ extension to the
Haskell module system.
The matching of the module signatures required by a
:pkg-field:`build-depends` dependency with the implementation modules
present in another dependency is triggered by a coincidence of names. When
the names of the signature and of the implementation are already the same,
the matching is automatic. But when the names don't coincide, or we want to
instantiate a signature in two different ways, adding mixin entries that
perform renamings becomes necessary.
.. Warning::
Backpack has the limitation that implementation modules that instantiate
signatures required by a :pkg-field:`build-depends` dependency can't
reside in the same component that has the dependency. They must reside
in a different package dependency, or at least in a separate internal
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment