docs/users_guide/shared_libs.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <sect1 id="using-shared-libs">
   3   <title>Using shared libraries</title>
   4   <indexterm><primary>Shared libraries</primary><secondary>using</secondary></indexterm>
   5   <indexterm><primary>Dynamic libraries</primary><secondary>using</secondary></indexterm>
   6
   7   <para>
   8     On some platforms GHC supports building Haskell code into shared
   9     libraries. Shared libraries are also sometimes known as dynamic
  10     libraries, in particular on Windows they are referred to as dynamic link
  11     libraries (DLLs).
  12   </para>
  13
  14   <para>
  15     Shared libraries allow a single instance of some pre-compiled code to be
  16     shared between several programs. In contrast, with static linking the
  17     code is copied into each program. Using shared libraries can thus save
  18     disk space. They also allow a single copy of code to be shared in memory
  19     between several programs that use it. Shared libraires are often used as
  20     a way of structuring large projects, especially where different parts are
  21     written in different programming languages. Shared libraries are also
  22     commonly used as a plugin mechanism by various applications. This is
  23     particularly common on Windows using COM.
  24   </para>
  25
  26   <para>
  27     In GHC version 6.12 building shared libraries is supported for Linux on
  28     x86 and x86-64 architectures and there is partial support on Windows (see
  29     <xref linkend="win32-dlls"/>). The crucial difference in support on
  30     Windows is that it is not currently possible to build each Haskell
  31     package as a separate DLL, it is only possible to link an entire Haskell
  32     program as one massive DLL.
  33   </para>
  34
  35   <para>
  36     Building and using shared libraries is slightly more complicated than
  37     building and using static libraries. When using Cabal much of the detail
  38     is hidden, just use <literal>--enable-shared</literal> when configuring a
  39     package to build it into a shared library, or to link it against other
  40     packages built as shared libraries. The additional complexity when
  41     building code is to distinguish whether the code will be used in a shared
  42     library or will use shared library versions of other packages it depends
  43     on. There is additional complexity when installing and distributing
  44     shared libraries or programs that use shared libraries, to ensure that
  45     all shared libraries that are required at runtime are present in suitable
  46     locations.
  47   </para>
  48
  49   <sect2>
  50     <title>Building programs that use shared libraries</title>
  51     <para>
  52       To build a simple program and have it use shared libraries for the
  53       runtime system and the base libraries use the
  54       <literal>-dynamic</literal> flag:
  55 <programlisting>
  56 ghc --make -dynamic Main.hs
  57 </programlisting>
  58       This has two effects. The first is to compile the code in such a way
  59       that it can be linked against shared library versions of Haskell
  60       packages (such as base). The second is when linking, to link against
  61       the shared versions of the packages' libraries rather than the static
  62       versions. Obviously this requires that the packages were build with
  63       shared libraries. On supported platforms GHC comes with shared
  64       libraries for all the core packages, but if you install extra packages
  65       (e.g. with Cabal) then they would also have to be built with shared
  66       libraries (<literal>--enable-shared</literal> for Cabal).
  67     </para>
  68   </sect2>
  69
  70   <sect2>
  71     <title>Building shared libraries</title>
  72     <para>
  73       To build some Haskell modules into a shared library use the
  74       <literal>-dynamic</literal>, <literal>-fPIC</literal> and
  75       <literal>-shared</literal> flags:
  76 <programlisting>
  77 ghc --make -dynamic -shared -fPIC Foo.hs -o libfoo.so
  78 </programlisting>
  79       As before, the <literal>-dynamic</literal> flag specifies that this
  80       library links against the shared library versions of the rts and base
  81       package. The <literal>-fPIC</literal> flag is required for all code
  82       that will end up in a shared library. The <literal>-shared</literal>
  83       flag specifies to make a shared library rather than a program. To make
  84       this clearer we can break this down into separate compliation and link
  85       steps:
  86 <programlisting>
  87 ghc -dynamic -fPIC -c Foo.hs
  88 ghc -dynamic -shared Foo.o -o libfoo.so
  89 </programlisting>
  90       In principle you can use <literal>-shared</literal> without
  91       <literal>-dynamic</literal> in the link step. That means to
  92       statically link the rts all the base libraries into your new shared
  93       library. This would make a very big, but standalone shared library.
  94       Indeed this is exactly what we must currently do on Windows where
  95       -dynamic is not yet supported (see <xref linkend="win32-dlls"/>).
  96       On most platforms however that would require all the static libraries
  97       to have been built with <literal>-fPIC</literal> so that the code is
  98       suitable to include into a shared library and we do not do that at the
  99       moment.
 100     </para>
 101   </sect2>
 102
 103   <sect2>
 104     <title>Shared libraries that export a C API</title>
 105     <para>
 106       Building Haskell code into a shared library is a good way to include
 107       Haskell code in a larger mixed-language project. While with static
 108       linking it is recommended to use GHC to perform the final link step,
 109       with shared libaries a Haskell library can be treated just like any
 110       other shared libary. The linking can be done using the normal system C
 111       compiler or linker.
 112     </para>
 113     <para>
 114       It is possible to load shared libraries generated by GHC in other
 115       programs not written in Haskell, so they are suitable for using as
 116       plugins. Of course to construct a plugin you will have to use the FFI
 117       to export C functions and follow the rules about initialising the RTS.
 118       See <xref linkend="ffi-library"/>. In particular you will probably want
 119       to export a C function from your shared library to initialise the
 120       plugin before any Haskell functions are called.
 121     </para>
 122   </sect2>
 123
 124   <sect2>
 125     <title>Shared libraries for Haskell packages</title>
 126     <para>
 127       When building Haskell packages as shared libraries to be used by other
 128       Haskell programs there are certain conventions that must be followed.
 129       These are handled by Cabal but for the details see <xref
 130       linkend="building-packages"/>.
 131    </para>
 132   </sect2>
 133
 134   <sect2 id="finding-shared-libs">
 135     <title>Finding shared libraries at runtime</title>
 136     <para>
 137       The primary difficulty with managing shared libraries is arranging
 138       things such that programs can find the libraries they need at runtime.
 139       The details of how this works varies between platforms, in particular
 140       the three major systems: Unix ELF platforms, Windows and Mac OS X.
 141     </para>
 142     <para>
 143       On Unix there are two mechanisms. Shared libraries can be installed
 144       into standard locations that the dynamic linker knows about. For
 145       example <literal>/usr/lib</literal> or
 146       <literal>/usr/local/lib</literal> on most systems. The other mechanism
 147       is to use a "runtime path" or "rpath" embedded into programs and
 148       libraries themselves. These paths can either be absolute paths or on at
 149       least Linux and Solaris they can be paths relative to the program or
 150       libary itself. In principle this makes it possible to construct fully
 151       relocatable sets of programs and libraries.
 152     </para>
 153     <para>
 154       GHC has a <literal>-dynload</literal> linking flag to select the method
 155       that is used to find shared libraries at runtime. There are currently
 156       three modes:
 157       <variablelist>
 158         <varlistentry>
 159           <term>sysdep</term>
 160           <listitem>
 161             <para>
 162               A system-dependent mode. This is also the default mode. On Unix
 163               ELF systems this embeds rpaths into the shared library or
 164               executable. In particular it uses absolute paths to where the
 165               shared libraries for the rts and each package can be found.
 166               This means the program can immediately be run and it will be
 167               able to find the libraries it needs. However it may not be
 168               suitable for deployment if the libraries are installed in a
 169               different location on another machine.
 170             </para>
 171           </listitem>
 172         </varlistentry>
 173         <varlistentry>
 174           <term>deploy</term>
 175           <listitem>
 176             <para>
 177               This does not embed any runtime paths. It relies on the shared
 178               libraries being available in a standard location or in a
 179               directory given by the <literal>LD_LIBRARY_PATH</literal>
 180               environment variable.
 181             </para>
 182           </listitem>
 183         </varlistentry>
 184         <varlistentry>
 185           <term>wrapped</term>
 186           <listitem>
 187             <para>
 188               This mode generates a wrapper program which in turn calls the
 189               real program (in the same directory but with a .dyn extension)
 190               in such a way that it can find the shared libraries that it
 191               needs. At the current time this mode is somewhat experimental.
 192             </para>
 193           </listitem>
 194         </varlistentry>
 195       </variablelist>
 196       To use relative paths for dependent libraries on Linux and Solaris you
 197       can use the <literal>deploy</literal> mode and pass suitable a -rpath
 198       flag to the linker:
 199 <programlisting>
 200 ghc -dynamic Main.hs -o main -lfoo -L. -optl-Wl,-rpath,'$ORIGIN'
 201 </programlisting>
 202       This assumes that the library <literal>libfoo.so</literal> is in the
 203       current directory and will be able to be found in the same directory as
 204       the executable <literal>main</literal> once the program is deployed.
 205       Similarly it would be possible to use a subdirectory relative to the
 206       executable e.g. <literal>-optl-Wl,-rpath,'$ORIGIN/lib'</literal>.
 207     </para>
 208   </sect2>
 209
 210 </sect1>