Commit f81df3c6 authored by Clemens Fruhwirth's avatar Clemens Fruhwirth
Browse files

Add documentation about -shared, shared library name mangling, and a xrefs

parent a6e4ca6e
......@@ -77,24 +77,36 @@ exposed-modules: Network.BSD,
<indexterm><primary><option>-package</option></primary></indexterm>
</term>
<listitem>
<para>This option causes the installed package <replaceable>P</replaceable> to be
exposed. The package <replaceable>P</replaceable> can be specified
in full with its version number
(e.g. <literal>network-1.0</literal>) or the version number can be
omitted if there is only one version of the package
installed.</para>
<para>If there are multiple versions of <replaceable>P</replaceable>
installed, then all other versions will become hidden.</para>
<para>This option causes the installed
package <replaceable>P</replaceable> to be exposed. The
package <replaceable>P</replaceable> can be specified in
full with its version number
(e.g. <literal>network-1.0</literal>) or the version
number can be omitted if there is only one version of the
package installed. If there are multiple versions
of <replaceable>P</replaceable> installed, then all other
versions will become hidden.</para>
<para>The <option>-package <replaceable>P</replaceable></option>
option also causes package <replaceable>P</replaceable> to be
linked into the resulting executable. In
<option>&ndash;&ndash;make</option> mode and GHCi, the compiler
normally determines which packages are required by the current
Haskell modules, and links only those. In batch mode however, the
dependency information isn't available, and explicit
<option>-package</option> options must be given when linking.</para>
option also causes package <replaceable>P</replaceable> to
be linked into the resulting executable or shared
object. Whether a packages' library is linked statically
or dynamically is controlled by the flag
pair <option>-static</option>/<option>-dynamic</option>.</para>
<para>In <option>&ndash;&ndash;make</option> mode
and <option>&ndash;&ndash;interactive</option> mode (see
<xref linkend="modes" />), the compiler normally
determines which packages are required by the current
Haskell modules, and links only those. In batch mode
however, the dependency information isn't available, and
explicit
<option>-package</option> options must be given when linking. The one other time you might need to use
<option>-package</option> to force linking a package is
when the package does not contain any Haskell modules (it
might contain a C library only, for example). In that
case, GHC will never discover a dependency on it, so it
has to be mentioned explicitly.</para>
<para>For example, to link a program consisting of objects
<filename>Foo.o</filename> and <filename>Main.o</filename>, where
......@@ -106,18 +118,7 @@ exposed-modules: Network.BSD,
The same flag is necessary even if we compiled the modules from
source, because GHC still reckons it's in batch mode:
<screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen>
In <literal>--make</literal> and <literal>--interactive</literal>
modes (<xref linkend="modes" />), however, GHC figures out the
packages required for linking without further assistance.</para>
<para>The one other time you might need to use
<option>-package</option> to force linking a package is when the
package does not contain any Haskell modules (it might contain a C
library only, for example). In that case, GHC
will never discover a dependency on it, so it has to be mentioned
explicitly.</para>
<screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen></para>
</listitem>
</varlistentry>
......@@ -348,65 +349,84 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
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>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>
</listitem>
<listitem>
<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 DLL on
Windows (e.g. <filename>HSfoo.dll</filename>). The
restriction to a single DLL on Windows is because the
package system is used to tell the compiler when it should
make an inter-DLL call rather than an intra-DLL call
(inter-DLL calls require an extra
indirection). <emphasis>Building packages as DLLs doesn't
work at the moment; see <xref linkend="win32-dlls-create"/>
for the gory details.</emphasis>
</para>
<para>Building a static library is done by using the
<listitem><para>Building a static library is done by using the
<literal>ar</literal> tool, like so:</para>
<screen>ar cqs libHSfoo.a A.o B.o C.o ...</screen>
<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>
<para>Versions of the Haskell libraries for use with GHCi
may also be included: GHCi cannot load <literal>.a</literal>
files directly, instead it will look for an object file
<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>
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 &ndash;&ndash;whole-archive -o HSfoo.o libHSfoo.a</screen>
<para>(replace
<literal>&ndash;&ndash;whole-archive</literal> with
<literal>&ndash;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>&ndash;&ndash;whole-archive</literal> with
<literal>&ndash;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>
</listitem>
</itemizedlist>
<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>
<para>To compile a module which is to be part of a new package,
<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
......@@ -416,8 +436,8 @@ $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
same as the package name stored in the <literal>.hi</literal>
file.</para>
<para>It is worth noting that on Windows, when each package
is built as a DLL, since a reference to a DLL costs an extra
<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>
......
......@@ -668,10 +668,7 @@ $ cat foo.hspp</screen>
<listitem>
<para>When generating code, assume that entities imported from a
different package will reside in a different shared library or
binary. This currently works on Mac OS X; it works on PowerPC Linux when
using the native code generator. As with <option>-fPIC</option>,
x86 Linux support is not quite ready yet. Windows is not supported,
and it is a no-op on PowerPC64 Linux.</para>
binary.</para>
<para>Note that this option also causes GHC to use shared libraries
when linking.</para>
</listitem>
......@@ -838,15 +835,45 @@ $ cat foo.hspp</screen>
<indexterm><primary><option>-dynamic</option></primary></indexterm>
</term>
<listitem>
<para>Tell the linker to use shared Haskell libraries, if
available (this option is only supported on Mac OS X at the
moment, and also note that your distribution of GHC may
not have been supplied with shared libraries).</para>
<para>This flag switches to shared Haskell libraries for
linking. See <xref linkend="building-packages" /> on how to
create them.</para>
<para>Note that this option also has an effect on
code generation (see above).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-shared</option>
<indexterm><primary><option>-shared</option></primary></indexterm>
</term>
<listitem>
<para>Instead of creating an executable, GHC produces a
shared object with this linker flag. Depending on the
operating system target, this might be an ELF DSO, a Windows
DLL, or a Mac OS dylib. GHC hides the operating system
details beneath this uniform flag.</para>
<para>The flags <option>-dynamic</option>/<option>-static</option> control whether the
resulting shared object links statically or dynamically to
Haskell package libraries given as <option>-package</option> option. Non-Haskell
libraries are linked as gcc would regularly link it on your
system, e.g. on most ELF system the linker uses the dynamic
libraries when found.</para>
<para>Object files linked into shared objects must be
compiled with <option>-fPIC</option>, see <xref linkend="options-codegen" /></para>
<para>When creating shared objects for Haskell packages, the
shared object must be named properly, so that GHC recognizes
the shared object when linked against this package. See
shared object name mangling.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-main-is <replaceable>thing</replaceable></option>
......
Markdown is supported
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