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>
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
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.
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.
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
50 <title>Building programs that use shared libraries</title>
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:
56 ghc --make -dynamic Main.hs
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).
71 <title>Shared libraries for Haskell packages</title>
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>
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
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"/>.
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).
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>.
116 <title>Shared libraries that export a C API</title>
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
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.
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:
139 ghc --make -dynamic -shared -fPIC Foo.hs -o libfoo.so
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
149 ghc -dynamic -fPIC -c Foo.hs
150 ghc -dynamic -shared Foo.o -o libfoo.so
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
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.
171 <sect2 id="finding-shared-libs">
172 <title>Finding shared libraries at runtime</title>
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.
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.
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
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.
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.
225 This mode generates a wrapper program which in turn calls the
226 real program (in the same directory but with a .dyn extension)
227 in such a way that it can find the shared libraries that it
228 needs. At the current time this mode is somewhat experimental.
233 To use relative paths for dependent libraries on Linux and Solaris you
234 can use the <literal>deploy</literal> mode and pass suitable a -rpath
237 ghc -dynamic Main.hs -o main -lfoo -L. -optl-Wl,-rpath,'$ORIGIN'
239 This assumes that the library <literal>libfoo.so</literal> is in the
240 current directory and will be able to be found in the same directory as
241 the executable <literal>main</literal> once the program is deployed.
242 Similarly it would be possible to use a subdirectory relative to the
243 executable e.g. <literal>-optl-Wl,-rpath,'$ORIGIN/lib'</literal>.
246 The standard assumption on Darwin/MacOS X is that dynamic libraries will
247 be stamped at build time with an "install name", which is the full
248 ultimate install path of the library file. Any libraries or executables
249 that subsequently link against it (even if it hasn't been installed yet)
250 will pick up that path as their runtime search location for it. When
251 compiling with ghc directly, the install name is set by default to the
252 location where it is built. You can override this with the
253 <literal>-dylib-install-name</literal> option (which passes
254 <literal>-install_name</literal> to the Apple linker). Cabal does this
255 for you. It automatically sets the install name for dynamic libraries to
256 the absolute path of the ultimate install location.