+ <title>Shared libraries for Haskell packages</title>
+ <para>
+ You can build Haskell code into a shared library and make a package to be
+ used by other Haskell programs. The easiest way is using Cabal, simply
+ configure the Cabal package with the <literal>--enable-shared</literal>
+ flag.
+ </para>
+ <para>
+ If you want to do the steps manually or are writing your own build
+ system then there are certain conventions that must be followed. Building
+ a shared library that exports Haskell code, to be used by other Haskell
+ code is a bit more complicated than it is for one that exports a C API
+ and will be used by C code. If you get it wrong you will usually end up
+ with linker errors.
+ </para>
+ <para>
+ In particular Haskell shared libraries <emphasis>must</emphasis> be
+ made into packages. You cannot freely assign which modules go in which
+ shared libraries. The Haskell shared libraries must match the package
+ boundaries. Most of the conventions GHC expects when using packages are
+ described in <xref linkend="building-packages"/>.
+ </para>
+ <para>
+ GHC handles references to symbols <emphasis>within</emphasis> the same
+ shared library (or main executable binary) differently from references
+ to symbols <emphasis>between</emphasis> different shared libraries. GHC
+ needs to know for each imported module if that module lives locally in
+ the same shared lib or in a separate shared lib. The way it does this
+ is by using packages. When using <literal>-dynamic</literal>, a module
+ from a separate package is assumed to come from a separate shared lib,
+ while modules from the same package (or the default "main" package) are
+ assumed to be within the same shared lib (or main executable binary).
+ </para>