This is a mechanism to eliminate the appeal of defining orphan instances
in Haskell packages.
The problem: If I define a new type class for which instances may be
defined for types defined in other packages, I must either depend on
those packages or ask that those packages' authors depend on my
The solution: Allow a library author to identify individual modules that
should only be built if a necessary dependency is included in a build in
which the library is involved.
A new `optionally-exposed` section of a library stanza supports the
specification of potentially exposed modules and their dependencies. The
inclusion of these modules and dependencies in the generated Cabal file
depends upon the availability of a build plan.
A build plan in this context is simply a list of package names and
versions as output by, for example, `stack list-dependencies`.
If no build plan is supplied, then all "optionally-exposed" modules are
exposed, and their dependencies must be available.
If a build plan is supplied, then only those "optionally-exposed"
modules whose dependencies are satisfied by the build plan are included
in the Cabal file generated for the package.
Usage by build tools:
A tool like stack can invoke `hpack --buildplan min` for each listed
dependency when computing an initial build plan. Then it can call
`hpack` for each package again, this time passing the name of a file
containing the computed build plan. This second round will not add any
new packages to the build plan, but may add dependencies to the
individual packages included in the build plan.
Usage by library authors:
If you wish to provide an instance for, say, `Data.Text.Text`, but do
not otherwise use the `text` package, place the instance definition in
its own module, say, `src/Foo/Text.hs`. Then add an
`optionally-exposed` section to the `library` definition so it looks
something like this,
dependencies: text > 1.2
Now, if somebody uses your library without themselves depending on
`text`, they may do so without incurring a dependency on `text`. If they
do depend on `text`, then they will have access to the instance you