- <literal>––whole-archive</literal> with
- <literal>–all_load</literal> on MacOS X)</para>
-
- <para>GHC does not maintain detailed cross-package
- dependency information. It does remember which modules in
- other packages the current module depends on, but not which
- things within those imported things.</para>
+ <literal>––whole-archive</literal> with
+ <literal>–all_load</literal> on MacOS X)</para>
+ </listitem>
+ <listitem>
+ <para>When building the package as shared object, GHC wraps
+ out the underlying linker so that the user gets a common
+ interface to all shared object variants that are supported
+ by GHC (DLLs, ELF DSOs, and Mac OS dylibs). The shared
+ object must be named in specific way for two reasons: (1)
+ the name must contain the GHC compiler version, so that two
+ library variants don't collide that are compiled by
+ different versions of GHC and that therefore are most likely
+ incompatible with respect to calling conventions, (2) it
+ must be different from the static name otherwise we would
+ not be able to control the linker as precisely as necessary
+ to make
+ the <option>-static</option>/<option>-dynamic</option> flags
+ work, see <xref linkend="options-linker" />.</para>
+
+<screen>ghc -shared libHSfoo-1.0-ghc<replaceable>GHCVersion</replaceable>.so A.o B.o C.o</screen>
+ <para>Using GHC's version number in the shared object name
+ allows different library versions compiled by different GHC
+ versions to be installed in standard system locations,
+ e.g. under *nix /usr/lib. To obtain the version number of
+ GHC invoke <literal>ghc --numeric-version</literal> and use
+ its output in place
+ of <replaceable>GHCVersion</replaceable>. See also
+ <xref linkend="options-codegen" /> on how object files must
+ be prepared for shared object linking.</para>