<?xml version="1.0" encoding="iso-8859-1"?>
<sect1 id="using-shared-libs">
  <title>Using shared libraries</title>
  <indexterm><primary>Shared libraries</primary><secondary>using</secondary></indexterm>
  <indexterm><primary>Dynamic libraries</primary><secondary>using</secondary></indexterm>

  <para>
    On some platforms GHC supports building Haskell code into shared
    libraries. Shared libraries are also sometimes known as dynamic
    libraries, in particular on Windows they are referred to as dynamic link
    libraries (DLLs).
  </para>

  <para>
    Shared libraries allow a single instance of some pre-compiled code to be
    shared between several programs. In contrast, with static linking the
    code is copied into each program. Using shared libraries can thus save
    disk space. They also allow a single copy of code to be shared in memory
    between several programs that use it. Shared libraries are often used as
    a way of structuring large projects, especially where different parts are
    written in different programming languages. Shared libraries are also
    commonly used as a plugin mechanism by various applications. This is
    particularly common on Windows using COM.
  </para>

  <para>
    In GHC version 6.12 building shared libraries is supported for Linux (on
    x86 and x86-64 architectures). GHC version 7.0 adds support on Windows
    (see <xref linkend="win32-dlls"/>), FreeBSD and OpenBSD (x86 and x86-64),
    Solaris (x86) and Mac OS X (x86 and PowerPC).
  </para>

  <para>
    Building and using shared libraries is slightly more complicated than
    building and using static libraries. When using Cabal much of the detail
    is hidden, just use <literal>--enable-shared</literal> when configuring a
    package to build it into a shared library, or to link it against other
    packages built as shared libraries. The additional complexity when
    building code is to distinguish whether the code will be used in a shared
    library or will use shared library versions of other packages it depends
    on. There is additional complexity when installing and distributing
    shared libraries or programs that use shared libraries, to ensure that
    all shared libraries that are required at runtime are present in suitable
    locations.
  </para>

  <sect2>
    <title>Building programs that use shared libraries</title>
    <para>
      To build a simple program and have it use shared libraries for the
      runtime system and the base libraries use the
      <literal>-dynamic</literal> flag:
<programlisting>
ghc --make -dynamic Main.hs
</programlisting>
      This has two effects. The first is to compile the code in such a way
      that it can be linked against shared library versions of Haskell
      packages (such as base). The second is when linking, to link against
      the shared versions of the packages' libraries rather than the static
      versions. Obviously this requires that the packages were built with
      shared libraries. On supported platforms GHC comes with shared
      libraries for all the core packages, but if you install extra packages
      (e.g. with Cabal) then they would also have to be built with shared
      libraries (<literal>--enable-shared</literal> for Cabal).
    </para>
  </sect2>

  <sect2>
    <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. The reason for this is that
      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>
    <para>
      Most of the conventions GHC expects when using packages are described
      in <xref linkend="building-packages"/>. In addition note that GHC
      expects the <literal>.hi</literal> files to use the extension
      <literal>.dyn_hi</literal>. The other requirements are the same as for
      C libraries and are described below, in particular the use of the flags
      <literal>-dynamic</literal>, <literal>-fPIC</literal> and
      <literal>-shared</literal>.
    </para>
  </sect2>

  <sect2>
    <title>Shared libraries that export a C API</title>
    <para>
      Building Haskell code into a shared library is a good way to include
      Haskell code in a larger mixed-language project. While with static
      linking it is recommended to use GHC to perform the final link step,
      with shared libraries a Haskell library can be treated just like any
      other shared library. The linking can be done using the normal system C
      compiler or linker.
    </para>
    <para>
      It is possible to load shared libraries generated by GHC in other
      programs not written in Haskell, so they are suitable for using as
      plugins. Of course to construct a plugin you will have to use the FFI
      to export C functions and follow the rules about initialising the RTS.
      See <xref linkend="ffi-library"/>. In particular you will probably want
      to export a C function from your shared library to initialise the
      plugin before any Haskell functions are called.
    </para>
    <para>
      To build Haskell modules that export a C API into a shared library use
      the <literal>-dynamic</literal>, <literal>-fPIC</literal> and
      <literal>-shared</literal> flags:
<programlisting>
ghc --make -dynamic -shared -fPIC Foo.hs -o libfoo.so
</programlisting>
      As before, the <literal>-dynamic</literal> flag specifies that this
      library links against the shared library versions of the rts and base
      package. The <literal>-fPIC</literal> flag is required for all code
      that will end up in a shared library. The <literal>-shared</literal>
      flag specifies to make a shared library rather than a program. To make
      this clearer we can break this down into separate compilation and link
      steps:
<programlisting>
ghc -dynamic -fPIC -c Foo.hs
ghc -dynamic -shared Foo.o -o libfoo.so
</programlisting>
      In principle you can use <literal>-shared</literal> without
      <literal>-dynamic</literal> in the link step. That means to
      statically link the rts all the base libraries into your new shared
      library. This would make a very big, but standalone shared library.
      On most platforms however that would require all the static libraries
      to have been built with <literal>-fPIC</literal> so that the code is
      suitable to include into a shared library and we do not do that at the
      moment.
    </para>
    <para>
      <emphasis>Warning:</emphasis> if your shared library exports a Haskell
      API then you cannot directly link it into another Haskell program and
      use that Haskell API. You will get linker errors. You must instead make
      it into a package as described in the section above.
    </para>
  </sect2>

  <sect2 id="finding-shared-libs">
    <title>Finding shared libraries at runtime</title>
    <para>
      The primary difficulty with managing shared libraries is arranging
      things such that programs can find the libraries they need at runtime.
      The details of how this works varies between platforms, in particular
      the three major systems: Unix ELF platforms, Windows and Mac OS X.
    </para>
    <sect3 id="finding-shared-libs-unix">
    <title>Unix</title>
    <para>
      On Unix there are two mechanisms. Shared libraries can be installed
      into standard locations that the dynamic linker knows about. For
      example <literal>/usr/lib</literal> or
      <literal>/usr/local/lib</literal> on most systems. The other mechanism
      is to use a "runtime path" or "rpath" embedded into programs and
      libraries themselves. These paths can either be absolute paths or on at
      least Linux and Solaris they can be paths relative to the program or
      library itself. In principle this makes it possible to construct fully
      relocatable sets of programs and libraries.
    </para>
    <para>
      GHC has a <literal>-dynload</literal> linking flag to select the method
      that is used to find shared libraries at runtime. There are currently
      two modes:
      <variablelist>
	<varlistentry>
	  <term>sysdep</term>
	  <listitem>
	    <para>
	      A system-dependent mode. This is also the default mode. On Unix
	      ELF systems this embeds
        <literal>RPATH</literal>/<literal>RUNPATH</literal> entries into the
        shared library or executable. In particular it uses absolute paths to
        where the shared libraries for the rts and each package can be found.
	      This means the program can immediately be run and it will be able to
        find the libraries it needs. However it may not be suitable for
        deployment if the libraries are installed in a different location on
        another machine.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>deploy</term>
	  <listitem>
	    <para>
	      This does not embed any runtime paths. It relies on the shared
	      libraries being available in a standard location or in a
	      directory given by the <literal>LD_LIBRARY_PATH</literal>
	      environment variable.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
      To use relative paths for dependent libraries on Linux and Solaris you
      can pass a suitable <literal>-rpath</literal> flag to the linker:
<programlisting>
ghc -dynamic Main.hs -o main -lfoo -L. -optl-Wl,-rpath,'$ORIGIN'
</programlisting>
      This assumes that the library <literal>libfoo.so</literal> is in the
      current directory and will be able to be found in the same directory as
      the executable <literal>main</literal> once the program is deployed.
      Similarly it would be possible to use a subdirectory relative to the
      executable e.g. <literal>-optl-Wl,-rpath,'$ORIGIN/lib'</literal>.
    </para>
    <para>
      This relative path technique can be used with either of the two
      <literal>-dynload</literal> modes, though it makes most sense with the
      <literal>deploy</literal> mode. The difference is that with the
      <literal>deploy</literal> mode, the above example will end up with an ELF
      <literal>RUNPATH</literal> of just <literal>$ORIGIN</literal> while with
      the <literal>sysdep</literal> mode the <literal>RUNPATH</literal> will be
      <literal>$ORIGIN</literal> followed by all the library directories of all
      the packages that the program depends on (e.g. <literal>base</literal>
      and <literal>rts</literal> packages etc.) which are typically absolute
      paths. The unix tool <literal>readelf --dynamic</literal> is handy for
      inspecting the <literal>RPATH</literal>/<literal>RUNPATH</literal>
      entries in ELF shared libraries and executables.
    </para>
    </sect3>
    <sect3 id="finding-shared-libs-mac">
    <title>Mac OS X</title>
    <para>
      The standard assumption on Darwin/Mac OS X is that dynamic libraries will
      be stamped at build time with an "install name", which is the full
      ultimate install path of the library file. Any libraries or executables
      that subsequently link against it (even if it hasn't been installed yet)
      will pick up that path as their runtime search location for it. When
      compiling with ghc directly, the install name is set by default to the
      location where it is built. You can override this with the
      <literal>-dylib-install-name</literal> option (which passes
      <literal>-install_name</literal> to the Apple linker). Cabal does this
      for you. It automatically sets the install name for dynamic libraries to
      the absolute path of the ultimate install location.
    </para>
    </sect3>
  </sect2>

</sect1>
