1 <refentry id="gmime-building" revision="11 Apr 2009">
3 <refentrytitle>Compiling the GMime libraries</refentrytitle>
4 <manvolnum>3</manvolnum>
5 <refmiscinfo>GMime Library</refmiscinfo>
8 <refname>Compiling the GMime Libraries</refname>
9 <refpurpose>How to compile GMime itself</refpurpose>
11 <refsect1 id="overview">
12 <title>Building GMime on UNIX-like systems</title>
14 This chapter covers building and installing GMime on UNIX and
15 UNIX-like systems such as Linux. Compiling GMime on Microsoft
16 Windows is not a goal of the project, however if you are able
17 build on a Microsoft Windows platform, do send me building and
18 installing instructions and I will add them to this document.
21 Before we get into the details of how to compile GMime, I should
22 mention that binary packages of GMime prebuilt for your operating
23 system may be available either from your operating system vendor
24 or from independent sources such as http://rpmfind.net. If you
25 can find them, it may be the easiest way of getting started
29 On UNIX-like systems GMime uses the standard GNU build system,
30 using <application>autoconf</application> for package
31 configuration and resolving portability issues,
32 <application>automake</application> for building makefiles that
33 comply with the GNU Coding Standards, and
34 <application>libtool</application> for building shared libraries
35 on multiple platforms.
38 If you are building GMime from the distributed source packages,
39 then you won't need these tools installed; the necessary pieces
40 of the tools are already included in the source packages. But
41 it's useful to know a bit about how packages that use these
42 tools work. A source package is distributed as a
43 <literal>tar.gz</literal> file which you unpack into a
44 directory full of the source files as follows:
47 tar -zxvf gmime-2.6.x.tar.gz
50 In the toplevel of the directory that is created, there will be
51 a shell script called <filename>configure</filename> which
52 you then run to take the template makefiles called
53 <filename>Makefile.in</filename> in the package and create
54 makefiles customized for your operating system. The
55 <filename>configure</filename> script can be passed various
56 command line arguments to determine how the package is built and
57 installed. The most commonly useful argument is the
58 <systemitem>--prefix</systemitem> argument which specifies where
59 the package is installed. To install a package into
60 <filename>/opt/gmime</filename> you would run configure as:
63 ./configure --prefix=/opt/gmime
66 A full list of options can be found by running
67 <filename>configure</filename> with the
68 <systemitem>--help</systemitem> argument. In general, the defaults
69 are right and should be trusted. After you've run
70 <filename>configure</filename>, you then run the
71 <command>make</command> command to build the package and install
79 If you don't have permission to write to the directory you are
80 installing in, you may have to change to root temporarily before
81 running <literal>make install</literal>. A quick way to do this is
82 to use the <command>su</command> command with the
83 <systemitem>-c</systemitem> option
84 (ex. <literal>su -c "make install"</literal>). Also, if you are
85 installing in a system directory, on some systems (such as
86 Linux), you will need to run <command>ldconfig</command> after
87 <literal>make install</literal> so that the newly installed
88 libraries will be found.
91 Several environment variables are useful to pass to set before
92 running configure. <envar>CPPFLAGS</envar> contains options to
93 pass to the C compiler, and is used to tell the compiler where
94 to look for include files. The <envar>LDFLAGS</envar> variable
95 is used in a similar fashion for the linker. Finally the
96 <envar>PKG_CONFIG_PATH</envar> environment variable contains
97 a search path that <command>pkg-config</command> (see below)
98 uses when looking for a file describing how to compile
99 programs using different libraries. If you were installing GMime
100 and it's dependencies into <filename>/opt/gmime</filename>, you
101 might want to set these variables as:
104 CPPFLAGS="-I/opt/gmime/include"
105 LDFLAGS="-L/opt/gmime/lib"
106 PKG_CONFIG_PATH="/opt/gmime/lib/pkgconfig"
107 export CPPFLAGS LDFLAGS PKG_CONFIG_PATH
110 You may also need to set the <envar>LD_LIBRARY_PATH</envar>
111 environment variable so the systems dynamic linker can find
112 the newly installed libraries, and the <envar>PATH</envar>
113 environment program so that utility binaries installed by
114 the various libraries will be found.
117 LD_LIBRARY_PATH="/opt/gmime/lib"
118 PATH="/opt/gmime/bin:$PATH"
119 export LD_LIBRARY_PATH PATH
122 <refsect1 id="dependencies">
123 <title>Dependencies</title>
125 Before you can compile the GMime library, you need to have
126 various other tools and libraries installed on your
127 system. The two tools needed during the build process (as
128 differentiated from the tools used in when creating GMime
129 mentioned above such as <application>autoconf</application>)
130 are <command>pkg-config</command> and GNU make.
134 <para><ulink url="http://www.freedesktop.org/software/pkgconfig/">pkg-config</ulink>
135 is a tool for tracking the compilation flags needed for
136 libraries that are used by the GMime libraries. (For each
137 library, a small <literal>.pc</literal> text file is installed in a standard
138 location that contains the compilation flags needed for that
139 library along with version number information.) The version
140 of <command>pkg-config</command> needed to build GMime is
141 mirrored in the <filename>dependencies</filename> directory
142 on the <ulink url="ftp://ftp.gtk.org/pub/gtk/v2.0/">GTK+ FTP
147 The GMime makefiles will mostly work with different versions
148 of <command>make</command>, however, there tends to be
149 a few incompatibilities, so the GMime team recommends
150 installing <ulink url="http://www.gnu.org/software/make">GNU
151 make</ulink> if you don't already have it on your system
152 and using it. (It may be called <command>gmake</command>
153 rather than <command>make</command>.)
158 GMime depends on the existance of two (2) libraries: GLib and iconv.
163 The GLib library provides core non-graphical functionality
164 such as high level data types, Unicode manipulation, and
165 a object and type system to C programs. It is available
166 from the <ulink url="ftp://ftp.gtk.org/pub/gtk/v2.0/">GTK+
172 The <ulink url="http://www.gnu.org/software/libiconv/">GNU
173 libiconv library</ulink> is needed to build GLib and GMime
174 if your system doesn't already have the
175 <function>iconv()</function> function for doing conversion
176 between character encodings. Most modern systems should have
177 <function>iconv()</function>.
182 <refsect1 id="building">
183 <title>Building and testing GMime</title>
185 First make sure that you have the necessary external
186 dependencies installed: <command>pkg-config</command>, GNU make,
187 and, if necessary, libiconv. To get detailed information about
188 building these packages, see the documentation provided with the
189 individual packages. On a newer Linux system, it's quite likely
190 that you'll have all of these installed already.
193 Then build and install the GMime libraries in the order:
194 libiconv, GLib, then GMime. For each library, follow the
195 steps of <literal>configure</literal>, <literal>make</literal>,
196 <literal>make install</literal> mentioned above. If you're
197 lucky, this will all go smoothly, and you'll be ready to
198 <link linkend="gmime-compiling">start compiling your own GMime
199 applications</link>. You can test your GMime installation
200 by running <command>pkg-config --modversion gmime-2.6</command>
201 and making sure that it can both find GMime and reports the
205 If one of the <filename>configure</filename> scripts fails or running
206 <command>make</command> fails, look closely at the error
207 messages printed; these will often provide useful information
208 as to what went wrong. When <filename>configure</filename>
209 fails, extra information, such as errors that a test compilation
210 ran into, is found in the file <filename>config.log</filename>.
211 Looking at the last couple of hundred lines in this file will
212 frequently make clear what went wrong. If all else fails, you
213 can ask for help by emailing me, fejj@gnome.org
216 <refsect1 id="extra-configuration-options">
217 <title>Extra Configuration Options</title>
219 In addition to the normal options, the
220 <command>configure</command> script for the GMime library
221 supports a number of additional arguments. (Command line
222 arguments for the other GMime libraries are described in
223 the documentation distributed with those libraries.)
225 <cmdsynopsis><command>./configure</command><group><arg>--enable-profiling</arg><arg>--enable-warnings</arg><arg>--enable-mono</arg><arg>--enable-gtk-doc</arg><arg>--enable-largfile</arg></group></cmdsynopsis>
229 <systemitem>--enable-profiling</systemitem>
232 Normally GMime will not pass the <literal>-pg</literal> flag to
233 <command>gcc</command> when building. This option will enable
234 the use of that flag thus building profiling information into
235 the GMime libraries for use with the GNU Profiler, gprof. Odds
236 are you do not care about this option unless you are either me
237 or desire to profile GMime and/or your program.
242 <systemitem>--enable-warnings</systemitem>
245 This option enables parser warnings about invalid MIME to be
246 logged to stderr at runtime. Again, it is unlikely you will
247 care to use this option.
252 <systemitem>--enable-mono</systemitem>
255 This option will include the Mono .NET bindings as part of
261 <systemitem>--enable-gtk-doc</systemitem>
264 This option will enable the building of the reference
265 documentation for GMime (e.g. the html pages you are
271 <systemitem>--enable-largefile</systemitem>
274 This option will enable large file support (e.g. files larger
275 than 2GB) on 32bit systems. This flag is enabled by default
276 starting with GMime 2.4.5.