docs/reference/building.sgml

   1 <refentry id="gmime-building" revision="11 Apr 2009">
   2   <refmeta>
   3     <refentrytitle>Compiling the GMime libraries</refentrytitle>
   4     <manvolnum>3</manvolnum>
   5     <refmiscinfo>GMime Library</refmiscinfo>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>Compiling the GMime Libraries</refname>
   9     <refpurpose>How to compile GMime itself</refpurpose>
  10   </refnamediv>
  11   <refsect1 id="overview">
  12     <title>Building GMime on UNIX-like systems</title>
  13     <para>
  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.
  19     </para>
  20     <para>
  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
  26       developing GMime.
  27     </para>
  28     <para>
  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.
  36     </para>
  37     <para>
  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:
  45     </para>
  46     <programlisting>
  47       tar -zxvf gmime-2.6.x.tar.gz
  48     </programlisting>
  49     <para>
  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:
  61     </para>
  62     <programlisting>
  63       ./configure --prefix=/opt/gmime
  64     </programlisting>
  65     <para>
  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
  72       it.
  73     </para>
  74     <programlisting>
  75       make
  76       make install
  77     </programlisting>
  78     <para>
  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 &quot;make install&quot;</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.
  89     </para>
  90     <para>
  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:
 102     </para>
 103     <programlisting>
 104       CPPFLAGS=&quot;-I/opt/gmime/include&quot;
 105       LDFLAGS=&quot;-L/opt/gmime/lib&quot;
 106       PKG_CONFIG_PATH=&quot;/opt/gmime/lib/pkgconfig&quot;
 107       export CPPFLAGS LDFLAGS PKG_CONFIG_PATH
 108     </programlisting>
 109     <para>
 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.
 115     </para>
 116     <programlisting>
 117       LD_LIBRARY_PATH=&quot;/opt/gmime/lib&quot;
 118       PATH=&quot;/opt/gmime/bin:$PATH&quot;
 119       export LD_LIBRARY_PATH PATH
 120     </programlisting>
 121   </refsect1>
 122   <refsect1 id="dependencies">
 123     <title>Dependencies</title>
 124     <para>
 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.
 131     </para>
 132     <itemizedlist>
 133       <listitem>
 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
 143           site.</ulink></para>
 144       </listitem>
 145       <listitem>
 146         <para>
 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>.)
 154         </para>
 155       </listitem>
 156     </itemizedlist>
 157     <para>
 158       GMime depends on the existance of two (2) libraries: GLib and iconv.
 159     </para>
 160     <itemizedlist>
 161       <listitem>
 162         <para>
 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+
 167           FTP site.</ulink>
 168         </para>
 169       </listitem>
 170       <listitem>
 171         <para>
 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>.
 178         </para>
 179       </listitem>
 180     </itemizedlist>
 181   </refsect1>
 182   <refsect1 id="building">
 183     <title>Building and testing GMime</title>
 184     <para>
 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.
 191     </para>
 192     <para>
 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
 202       correct version.
 203     </para>
 204     <para>
 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
 214     </para>
 215   </refsect1>
 216   <refsect1 id="extra-configuration-options">
 217     <title>Extra Configuration Options</title>
 218     <para>
 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.)
 224
 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>
 226     </para>
 227     <formalpara>
 228       <title>
 229         <systemitem>--enable-profiling</systemitem>
 230       </title>
 231       <para>
 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.
 238       </para>
 239     </formalpara>
 240     <formalpara>
 241       <title>
 242         <systemitem>--enable-warnings</systemitem>
 243       </title>
 244       <para>
 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.
 248       </para>
 249     </formalpara>
 250     <formalpara>
 251       <title>
 252         <systemitem>--enable-mono</systemitem>
 253       </title>
 254       <para>
 255         This option will include the Mono .NET bindings as part of
 256         the build.
 257       </para>
 258     </formalpara>
 259     <formalpara>
 260       <title>
 261         <systemitem>--enable-gtk-doc</systemitem>
 262       </title>
 263       <para>
 264         This option will enable the building of the reference
 265         documentation for GMime (e.g. the html pages you are
 266         reading now).
 267       </para>
 268     </formalpara>
 269     <formalpara>
 270       <title>
 271         <systemitem>--enable-largefile</systemitem>
 272       </title>
 273       <para>
 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.
 277       </para>
 278     </formalpara>
 279   </refsect1>
 280 </refentry>