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 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.
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).
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
48 <title>Building programs that use shared libraries</title>
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:
54 ghc --make -dynamic Main.hs
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).
69 <title>Shared libraries for Haskell packages</title>
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>
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
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).
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>.
111 <title>Shared libraries that export a C API</title>
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 libraries a Haskell library can be treated just like any
117 other shared library. The linking can be done using the normal system C
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.
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:
134 ghc --make -dynamic -shared -fPIC Foo.hs -o libfoo.so
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 compilation and link
144 ghc -dynamic -fPIC -c Foo.hs
145 ghc -dynamic -shared Foo.o -o libfoo.so
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
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.
164 <sect2 id="finding-shared-libs">
165 <title>Finding shared libraries at runtime</title>
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.
172 <sect3 id="finding-shared-libs-unix">
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 library itself. In principle this makes it possible to construct fully
183 relocatable sets of programs and libraries.
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
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
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.
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:
221 ghc -dynamic Main.hs -o main -lfoo -L. -optl-Wl,-rpath,'$ORIGIN'
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>.
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.
244 <sect3 id="finding-shared-libs-mac">
245 <title>Mac OS X</title>
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.