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