+ <sect2 id="building-packages">
+ <title>Building a package from Haskell source</title>
+ <indexterm><primary>packages</primary>
+ <secondary>building</secondary></indexterm>
+
+ <para>We don't recommend building packages the hard way. Instead, use the
+ <ulink url="../Cabal/index.html">Cabal</ulink> infrastructure
+ if possible. If your package is particularly complicated or requires a
+ lot of configuration, then you might have to fall back to the low-level
+ mechanisms, so a few hints for those brave souls follow.</para>
+
+ <para>You need to build an "installed package info" file for
+ passing to <literal>ghc-pkg</literal> when installing your
+ package. The contents of this file are described in
+ <xref linkend="installed-pkg-info" />.</para>
+
+ <para>The Haskell code in a package may be built into one or more
+ archive libraries (e.g. <filename>libHSfoo.a</filename>), or a
+ single shared object
+ (e.g. <filename>libHSfoo.dll/.so/.dylib</filename>). The
+ restriction to a single shared object is because the package
+ system is used to tell the compiler when it should make an
+ inter-shared-object call rather than an intra-shared-object-call
+ call (inter-shared-object calls require an extra
+ indirection).</para>
+ <itemizedlist>
+ <listitem><para>Building a static library is done by using the
+ <literal>ar</literal> tool, like so:</para>
+
+<screen>ar cqs libHSfoo-1.0.a A.o B.o C.o ...</screen>
+
+ <para>where <filename>A.o</filename>,
+ <filename>B.o</filename> and so on are the compiled Haskell
+ modules, and <filename>libHSfoo.a</filename> is the library you
+ wish to create. The syntax may differ slightly on your system,
+ so check the documentation if you run into difficulties.</para>
+ </listitem>
+ <listitem>
+ <para>Versions of the Haskell libraries for use with GHCi may also
+ abe included: GHCi cannot load <literal>.a</literal> files
+ directly, instead it will look for an object file
+ called <filename>HSfoo.o</filename> and load that. On some
+ systems, the <literal>ghc-pkg</literal> tool can automatically
+ build the GHCi version of each library, see
+ <xref linkend="package-management"/>. To build these libraries
+ by hand from the <literal>.a</literal> archive, it is possible
+ to use GNU <command>ld</command> as follows:</para>
+
+<screen>ld -r ––whole-archive -o HSfoo.o libHSfoo.a</screen>
+
+ <para>(replace
+ <literal>––whole-archive</literal> with
+ <literal>–all_load</literal> on MacOS X)</para>
+ </listitem>
+ <listitem>
+ <para>When building the package as shared library, GHC can be used to
+ perform the link step. This hides some of the details
+ out the underlying linker and provides 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>
+ </listitem>
+ </itemizedlist>
+
+ <para>To compile a module which is to be part of a new package,
+ use the <literal>-package-name</literal> option (<xref linkend="using-packages"/>).
+ Failure to use the <literal>-package-name</literal> option
+ when compiling a package will probably result in disaster, but
+ you will only discover later when you attempt to import modules
+ from the package. At this point GHC will complain that the
+ package name it was expecting the module to come from is not the
+ same as the package name stored in the <literal>.hi</literal>
+ file.</para>
+
+ <para>It is worth noting with shared objects, when each package
+ is built as a single shared object file, since a reference to a shared object costs an extra
+ indirection, intra-package references are cheaper than
+ inter-package references. Of course, this applies to the
+ <filename>main</filename> package as well.</para>
+ </sect2>
+
projects / ghc-hetmet.git / commitdiff