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 libraries 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). GHC version 7.0 adds support on Windows
  29     (see <xref linkend="win32-dlls"/>), FreeBSD and OpenBSD (x86 and x86-64),
  30     Solaris (x86) and Mac OS X (x86 and PowerPC).
  31   </para>
  32
  33   <para>
  34     Building and using shared libraries is slightly more complicated than
  35     building and using static libraries. When using Cabal much of the detail
  36     is hidden, just use <literal>--enable-shared</literal> when configuring a
  37     package to build it into a shared library, or to link it against other
  38     packages built as shared libraries. The additional complexity when
  39     building code is to distinguish whether the code will be used in a shared
  40     library or will use shared library versions of other packages it depends
  41     on. There is additional complexity when installing and distributing
  42     shared libraries or programs that use shared libraries, to ensure that
  43     all shared libraries that are required at runtime are present in suitable
  44     locations.
  45   </para>
  46
  47   <sect2>
  48     <title>Building programs that use shared libraries</title>
  49     <para>
  50       To build a simple program and have it use shared libraries for the
  51       runtime system and the base libraries use the
  52       <literal>-dynamic</literal> flag:
  53 <programlisting>
  54 ghc --make -dynamic Main.hs
  55 </programlisting>
  56       This has two effects. The first is to compile the code in such a way
  57       that it can be linked against shared library versions of Haskell
  58       packages (such as base). The second is when linking, to link against
  59       the shared versions of the packages' libraries rather than the static
  60       versions. Obviously this requires that the packages were built with
  61       shared libraries. On supported platforms GHC comes with shared
  62       libraries for all the core packages, but if you install extra packages
  63       (e.g. with Cabal) then they would also have to be built with shared
  64       libraries (<literal>--enable-shared</literal> for Cabal).
  65     </para>
  66   </sect2>
  67
  68   <sect2>
  69     <title>Shared libraries for Haskell packages</title>
  70     <para>
  71       You can build Haskell code into a shared library and make a package to be
  72       used by other Haskell programs. The easiest way is using Cabal, simply
  73       configure the Cabal package with the <literal>--enable-shared</literal>
  74       flag.
  75     </para>
  76     <para>
  77       If you want to do the steps manually or are writing your own build
  78       system then there are certain conventions that must be followed. Building
  79       a shared library that exports Haskell code, to be used by other Haskell
  80       code is a bit more complicated than it is for one that exports a C API
  81       and will be used by C code. If you get it wrong you will usually end up
  82       with linker errors.
  83     </para>
  84     <para>
  85       In particular Haskell shared libraries <emphasis>must</emphasis> be
  86       made into packages. You cannot freely assign which modules go in which
  87       shared libraries. The Haskell shared libraries must match the package
  88       boundaries. The reason for this is that
  89       GHC handles references to symbols <emphasis>within</emphasis> the same
  90       shared library (or main executable binary) differently from references
  91       to symbols <emphasis>between</emphasis> different shared libraries. GHC
  92       needs to know for each imported module if that module lives locally in
  93       the same shared lib or in a separate shared lib. The way it does this
  94       is by using packages. When using <literal>-dynamic</literal>, a module
  95       from a separate package is assumed to come from a separate shared lib,
  96       while modules from the same package (or the default "main" package) are
  97       assumed to be within the same shared lib (or main executable binary).
  98    </para>
  99     <para>
 100       Most of the conventions GHC expects when using packages are described
 101       in <xref linkend="building-packages"/>. In addition note that GHC
 102       expects the <literal>.hi</literal> files to use the extension
 103       <literal>.dyn_hi</literal>. The other requirements are the same as for
 104       C libraries and are described below, in particular the use of the flags
 105       <literal>-dynamic</literal>, <literal>-fPIC</literal> and
 106       <literal>-shared</literal>.
 107     </para>
 108   </sect2>
 109
 110   <sect2>
 111     <title>Shared libraries that export a C API</title>
 112     <para>
 113       Building Haskell code into a shared library is a good way to include
 114       Haskell code in a larger mixed-language project. While with static
 115       linking it is recommended to use GHC to perform the final link step,
 116       with shared libaries a Haskell library can be treated just like any
 117       other shared libary. The linking can be done using the normal system C
 118       compiler or linker.
 119     </para>
 120     <para>
 121       It is possible to load shared libraries generated by GHC in other
 122       programs not written in Haskell, so they are suitable for using as
 123       plugins. Of course to construct a plugin you will have to use the FFI
 124       to export C functions and follow the rules about initialising the RTS.
 125       See <xref linkend="ffi-library"/>. In particular you will probably want
 126       to export a C function from your shared library to initialise the
 127       plugin before any Haskell functions are called.
 128     </para>
 129     <para>
 130       To build Haskell modules that export a C API into a shared library use
 131       the <literal>-dynamic</literal>, <literal>-fPIC</literal> and
 132       <literal>-shared</literal> flags:
 133 <programlisting>
 134 ghc --make -dynamic -shared -fPIC Foo.hs -o libfoo.so
 135 </programlisting>
 136       As before, the <literal>-dynamic</literal> flag specifies that this
 137       library links against the shared library versions of the rts and base
 138       package. The <literal>-fPIC</literal> flag is required for all code
 139       that will end up in a shared library. The <literal>-shared</literal>
 140       flag specifies to make a shared library rather than a program. To make
 141       this clearer we can break this down into separate compliation and link
 142       steps:
 143 <programlisting>
 144 ghc -dynamic -fPIC -c Foo.hs
 145 ghc -dynamic -shared Foo.o -o libfoo.so
 146 </programlisting>
 147       In principle you can use <literal>-shared</literal> without
 148       <literal>-dynamic</literal> in the link step. That means to
 149       statically link the rts all the base libraries into your new shared
 150       library. This would make a very big, but standalone shared library.
 151       On most platforms however that would require all the static libraries
 152       to have been built with <literal>-fPIC</literal> so that the code is
 153       suitable to include into a shared library and we do not do that at the
 154       moment.
 155     </para>
 156     <para>
 157       <emphasis>Warning:</emphasis> if your shared library exports a Haskell
 158       API then you cannot directly link it into another Haskell program and
 159       use that Haskell API. You will get linker errors. You must instead make
 160       it into a package as described in the section above.
 161     </para>
 162   </sect2>
 163
 164   <sect2 id="finding-shared-libs">
 165     <title>Finding shared libraries at runtime</title>
 166     <para>
 167       The primary difficulty with managing shared libraries is arranging
 168       things such that programs can find the libraries they need at runtime.
 169       The details of how this works varies between platforms, in particular
 170       the three major systems: Unix ELF platforms, Windows and Mac OS X.
 171     </para>
 172     <sect3 id="finding-shared-libs-unix">
 173     <title>Unix</title>
 174     <para>
 175       On Unix there are two mechanisms. Shared libraries can be installed
 176       into standard locations that the dynamic linker knows about. For
 177       example <literal>/usr/lib</literal> or
 178       <literal>/usr/local/lib</literal> on most systems. The other mechanism
 179       is to use a "runtime path" or "rpath" embedded into programs and
 180       libraries themselves. These paths can either be absolute paths or on at
 181       least Linux and Solaris they can be paths relative to the program or
 182       libary itself. In principle this makes it possible to construct fully
 183       relocatable sets of programs and libraries.
 184     </para>
 185     <para>
 186       GHC has a <literal>-dynload</literal> linking flag to select the method
 187       that is used to find shared libraries at runtime. There are currently
 188       two modes:
 189       <variablelist>
 190         <varlistentry>
 191           <term>sysdep</term>
 192           <listitem>
 193             <para>
 194               A system-dependent mode. This is also the default mode. On Unix
 195               ELF systems this embeds
 196         <literal>RPATH</literal>/<literal>RUNPATH</literal> entries into the
 197         shared library or executable. In particular it uses absolute paths to
 198         where the shared libraries for the rts and each package can be found.
 199               This means the program can immediately be run and it will be able to
 200         find the libraries it needs. However it may not be suitable for
 201         deployment if the libraries are installed in a different location on
 202         another machine.
 203             </para>
 204           </listitem>
 205         </varlistentry>
 206         <varlistentry>
 207           <term>deploy</term>
 208           <listitem>
 209             <para>
 210               This does not embed any runtime paths. It relies on the shared
 211               libraries being available in a standard location or in a
 212               directory given by the <literal>LD_LIBRARY_PATH</literal>
 213               environment variable.
 214             </para>
 215           </listitem>
 216         </varlistentry>
 217       </variablelist>
 218       To use relative paths for dependent libraries on Linux and Solaris you
 219       can pass a suitable <literal>-rpath</literal> flag to the linker:
 220 <programlisting>
 221 ghc -dynamic Main.hs -o main -lfoo -L. -optl-Wl,-rpath,'$ORIGIN'
 222 </programlisting>
 223       This assumes that the library <literal>libfoo.so</literal> is in the
 224       current directory and will be able to be found in the same directory as
 225       the executable <literal>main</literal> once the program is deployed.
 226       Similarly it would be possible to use a subdirectory relative to the
 227       executable e.g. <literal>-optl-Wl,-rpath,'$ORIGIN/lib'</literal>.
 228     </para>
 229     <para>
 230       This relative path technique can be used with either of the two
 231       <literal>-dynload</literal> modes, though it makes most sense with the
 232       <literal>deploy</literal> mode. The difference is that with the
 233       <literal>deploy</literal> mode, the above example will end up with an ELF
 234       <literal>RUNPATH</literal> of just <literal>$ORIGIN</literal> while with
 235       the <literal>sysdep</literal> mode the <literal>RUNPATH</literal> will be
 236       <literal>$ORIGIN</literal> followed by all the library directories of all
 237       the packages that the program depends on (e.g. <literal>base</literal>
 238       and <literal>rts</literal> packages etc.) which are typically absolute
 239       paths. The unix tool <literal>readelf --dynamic</literal> is handy for
 240       inspecting the <literal>RPATH</literal>/<literal>RUNPATH</literal>
 241       entries in ELF shared libraries and executables.
 242     </para>
 243     </sect3>
 244     <sect3 id="finding-shared-libs-mac">
 245     <title>Mac OS X</title>
 246     <para>
 247       The standard assumption on Darwin/Mac OS X is that dynamic libraries will
 248       be stamped at build time with an "install name", which is the full
 249       ultimate install path of the library file. Any libraries or executables
 250       that subsequently link against it (even if it hasn't been installed yet)
 251       will pick up that path as their runtime search location for it. When
 252       compiling with ghc directly, the install name is set by default to the
 253       location where it is built. You can override this with the
 254       <literal>-dylib-install-name</literal> option (which passes
 255       <literal>-install_name</literal> to the Apple linker). Cabal does this
 256       for you. It automatically sets the install name for dynamic libraries to
 257       the absolute path of the ultimate install location.
 258     </para>
 259     </sect3>
 260   </sect2>
 261
 262 </sect1>