docs/reference/html/gmime-building.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Compiling the GMime libraries</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GMime 2.6 Reference Manual">
   8 <link rel="up" href="gmime.html" title="Part I. GMime Overview">
   9 <link rel="prev" href="gmime.html" title="Part I. GMime Overview">
  10 <link rel="next" href="gmime-compiling.html" title="Compiling GMime Applications">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
  16 <td><a accesskey="p" href="gmime.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  17 <td><a accesskey="u" href="gmime.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  18 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  19 <th width="100%" align="center">GMime 2.6 Reference Manual</th>
  20 <td><a accesskey="n" href="gmime-compiling.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="refentry">
  23 <a name="gmime-building"></a><div class="titlepage"></div>
  24 <div class="refnamediv"><table width="100%"><tr>
  25 <td valign="top">
  26 <h2><span class="refentrytitle">Compiling the GMime libraries</span></h2>
  27 <p>Compiling the GMime Libraries — How to compile GMime itself</p>
  28 </td>
  29 <td valign="top" align="right"></td>
  30 </tr></table></div>
  31 <div class="refsect1">
  32 <a name="overview"></a><h2>Building GMime on UNIX-like systems</h2>
  33 <p>
  34       This chapter covers building and installing GMime on UNIX and
  35       UNIX-like systems such as Linux. Compiling GMime on Microsoft
  36       Windows is not a goal of the project, however if you are able
  37       build on a Microsoft Windows platform, do send me building and
  38       installing instructions and I will add them to this document.
  39     </p>
  40 <p>
  41       Before we get into the details of how to compile GMime, I should
  42       mention that binary packages of GMime prebuilt for your operating
  43       system may be available either from your operating system vendor
  44       or from independent sources such as http://rpmfind.net. If you
  45       can find them, it may be the easiest way of getting started
  46       developing GMime.
  47     </p>
  48 <p>
  49       On UNIX-like systems GMime uses the standard GNU build system,
  50       using <span class="application">autoconf</span> for package
  51       configuration and resolving portability issues,
  52       <span class="application">automake</span> for building makefiles that
  53       comply with the GNU Coding Standards, and
  54       <span class="application">libtool</span> for building shared libraries
  55       on multiple platforms.
  56     </p>
  57 <p>
  58       If you are building GMime from the distributed source packages,
  59       then you won't need these tools installed; the necessary pieces
  60       of the tools are already included in the source packages. But
  61       it's useful to know a bit about how packages that use these
  62       tools work. A source package is distributed as a
  63       <code class="literal">tar.gz</code> file which you unpack into a
  64       directory full of the source files as follows:
  65     </p>
  66 <pre class="programlisting">
  67       tar -zxvf gmime-2.6.x.tar.gz
  68     </pre>
  69 <p>
  70       In the toplevel of the directory that is created, there will be
  71       a shell script called <code class="filename">configure</code> which
  72       you then run to take the template makefiles called
  73       <code class="filename">Makefile.in</code> in the package and create
  74       makefiles customized for your operating system. The
  75       <code class="filename">configure</code> script can be passed various
  76       command line arguments to determine how the package is built and
  77       installed. The most commonly useful argument is the
  78       <code class="systemitem">--prefix</code> argument which specifies where
  79       the package is installed. To install a package into
  80       <code class="filename">/opt/gmime</code> you would run configure as:
  81     </p>
  82 <pre class="programlisting">
  83       ./configure --prefix=/opt/gmime
  84     </pre>
  85 <p>
  86       A full list of options can be found by running
  87       <code class="filename">configure</code> with the
  88       <code class="systemitem">--help</code> argument. In general, the defaults
  89       are right and should be trusted. After you've run
  90       <code class="filename">configure</code>, you then run the
  91       <span class="command"><strong>make</strong></span> command to build the package and install
  92       it.
  93     </p>
  94 <pre class="programlisting">
  95       make
  96       make install
  97     </pre>
  98 <p>
  99       If you don't have permission to write to the directory you are
 100       installing in, you may have to change to root temporarily before
 101       running <code class="literal">make install</code>. A quick way to do this is
 102       to use the <span class="command"><strong>su</strong></span> command with the
 103       <code class="systemitem">-c</code> option
 104       (ex. <code class="literal">su -c "make install"</code>). Also, if you are
 105       installing in a system directory, on some systems (such as
 106       Linux), you will need to run <span class="command"><strong>ldconfig</strong></span> after
 107       <code class="literal">make install</code> so that the newly installed
 108       libraries will be found.
 109     </p>
 110 <p>
 111       Several environment variables are useful to pass to set before
 112       running configure. <code class="envar">CPPFLAGS</code> contains options to
 113       pass to the C compiler, and is used to tell the compiler where
 114       to look for include files. The <code class="envar">LDFLAGS</code> variable
 115       is used in a similar fashion for the linker. Finally the
 116       <code class="envar">PKG_CONFIG_PATH</code> environment variable contains
 117       a search path that <span class="command"><strong>pkg-config</strong></span> (see below)
 118       uses when looking for a file describing how to compile
 119       programs using different libraries. If you were installing GMime
 120       and it's dependencies into <code class="filename">/opt/gmime</code>, you
 121       might want to set these variables as:
 122     </p>
 123 <pre class="programlisting">
 124       CPPFLAGS="-I/opt/gmime/include"
 125       LDFLAGS="-L/opt/gmime/lib"
 126       PKG_CONFIG_PATH="/opt/gmime/lib/pkgconfig"
 127       export CPPFLAGS LDFLAGS PKG_CONFIG_PATH
 128     </pre>
 129 <p>
 130       You may also need to set the <code class="envar">LD_LIBRARY_PATH</code>
 131       environment variable so the systems dynamic linker can find
 132       the newly installed libraries, and the <code class="envar">PATH</code>
 133       environment program so that utility binaries installed by
 134       the various libraries will be found.
 135     </p>
 136 <pre class="programlisting">
 137       LD_LIBRARY_PATH="/opt/gmime/lib"
 138       PATH="/opt/gmime/bin:$PATH"
 139       export LD_LIBRARY_PATH PATH
 140     </pre>
 141 </div>
 142 <div class="refsect1">
 143 <a name="dependencies"></a><h2>Dependencies</h2>
 144 <p>
 145       Before you can compile the GMime library, you need to have
 146       various other tools and libraries installed on your
 147       system. The two tools needed during the build process (as
 148       differentiated from the tools used in when creating GMime
 149       mentioned above such as <span class="application">autoconf</span>)
 150       are <span class="command"><strong>pkg-config</strong></span> and GNU make.
 151     </p>
 152 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
 153 <li class="listitem"><p><a class="ulink" href="http://www.freedesktop.org/software/pkgconfig/" target="_top">pkg-config</a>
 154           is a tool for tracking the compilation flags needed for
 155           libraries that are used by the GMime libraries. (For each
 156           library, a small <code class="literal">.pc</code> text file is installed in a standard
 157           location that contains the compilation flags needed for that
 158           library along with version number information.)  The version
 159           of <span class="command"><strong>pkg-config</strong></span> needed to build GMime is
 160           mirrored in the <code class="filename">dependencies</code> directory
 161           on the <a class="ulink" href="ftp://ftp.gtk.org/pub/gtk/v2.0/" target="_top">GTK+ FTP
 162           site.</a></p></li>
 163 <li class="listitem"><p>
 164           The GMime makefiles will mostly work with different versions
 165           of <span class="command"><strong>make</strong></span>, however, there tends to be
 166           a few incompatibilities, so the GMime team recommends
 167           installing <a class="ulink" href="http://www.gnu.org/software/make" target="_top">GNU
 168             make</a> if you don't already have it on your system
 169           and using it. (It may be called <span class="command"><strong>gmake</strong></span>
 170           rather than <span class="command"><strong>make</strong></span>.)
 171         </p></li>
 172 </ul></div>
 173 <p>
 174       GMime depends on the existance of two (2) libraries: GLib and iconv.
 175     </p>
 176 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
 177 <li class="listitem"><p>
 178           The GLib library provides core non-graphical functionality
 179           such as high level data types, Unicode manipulation, and
 180           a object and type system to C programs. It is available
 181           from the <a class="ulink" href="ftp://ftp.gtk.org/pub/gtk/v2.0/" target="_top">GTK+
 182           FTP site.</a>
 183         </p></li>
 184 <li class="listitem"><p>
 185           The <a class="ulink" href="http://www.gnu.org/software/libiconv/" target="_top">GNU
 186           libiconv library</a> is needed to build GLib and GMime
 187           if your system doesn't already have the
 188           <code class="function">iconv()</code> function for doing conversion
 189           between character encodings. Most modern systems should have
 190           <code class="function">iconv()</code>.
 191         </p></li>
 192 </ul></div>
 193 </div>
 194 <div class="refsect1">
 195 <a name="building"></a><h2>Building and testing GMime</h2>
 196 <p>
 197       First make sure that you have the necessary external
 198       dependencies installed: <span class="command"><strong>pkg-config</strong></span>, GNU make,
 199       and, if necessary, libiconv. To get detailed information about
 200       building these packages, see the documentation provided with the
 201       individual packages. On a newer Linux system, it's quite likely
 202       that you'll have all of these installed already.
 203     </p>
 204 <p>
 205       Then build and install the GMime libraries in the order:
 206       libiconv, GLib, then GMime. For each library, follow the
 207       steps of <code class="literal">configure</code>, <code class="literal">make</code>,
 208       <code class="literal">make install</code> mentioned above. If you're
 209       lucky, this will all go smoothly, and you'll be ready to
 210       <a class="link" href="gmime-compiling.html" title="Compiling GMime Applications">start compiling your own GMime
 211         applications</a>. You can test your GMime installation
 212       by running <span class="command"><strong>pkg-config --modversion gmime-2.6</strong></span>
 213       and making sure that it can both find GMime and reports the
 214       correct version.
 215     </p>
 216 <p>
 217       If one of the <code class="filename">configure</code> scripts fails or running
 218       <span class="command"><strong>make</strong></span> fails, look closely at the error
 219       messages printed; these will often provide useful information
 220       as to what went wrong. When <code class="filename">configure</code>
 221       fails, extra information, such as errors that a test compilation
 222       ran into, is found in the file <code class="filename">config.log</code>.
 223       Looking at the last couple of hundred lines in this file will
 224       frequently make clear what went wrong. If all else fails, you
 225       can ask for help by emailing me, fejj@gnome.org
 226     </p>
 227 </div>
 228 <div class="refsect1">
 229 <a name="extra-configuration-options"></a><h2>Extra Configuration Options</h2>
 230 <p>
 231         In addition to the normal options, the
 232         <span class="command"><strong>configure</strong></span> script for the GMime library
 233         supports a number of additional arguments. (Command line
 234         arguments for the other GMime libraries are described in
 235         the documentation distributed with those libraries.)
 236
 237         </p>
 238 <div class="cmdsynopsis"><p><code class="command">./configure</code>  [[--enable-profiling] |  [--enable-warnings] |  [--enable-mono] |  [--enable-gtk-doc] |  [--enable-largfile]]</p></div>
 239 <p>
 240     </p>
 241 <p><b>
 242         <code class="systemitem">--enable-profiling</code>
 243       . </b>
 244         Normally GMime will not pass the <code class="literal">-pg</code> flag to
 245         <span class="command"><strong>gcc</strong></span> when building. This option will enable
 246         the use of that flag thus building profiling information into
 247         the GMime libraries for use with the GNU Profiler, gprof. Odds
 248         are you do not care about this option unless you are either me
 249         or desire to profile GMime and/or your program.
 250       </p>
 251 <p><b>
 252         <code class="systemitem">--enable-warnings</code>
 253       . </b>
 254         This option enables parser warnings about invalid MIME to be
 255         logged to stderr at runtime. Again, it is unlikely you will
 256         care to use this option.
 257       </p>
 258 <p><b>
 259         <code class="systemitem">--enable-mono</code>
 260       . </b>
 261         This option will include the Mono .NET bindings as part of
 262         the build.
 263       </p>
 264 <p><b>
 265         <code class="systemitem">--enable-gtk-doc</code>
 266       . </b>
 267         This option will enable the building of the reference
 268         documentation for GMime (e.g. the html pages you are
 269         reading now).
 270       </p>
 271 <p><b>
 272         <code class="systemitem">--enable-largefile</code>
 273       . </b>
 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       </p>
 278 </div>
 279 </div>
 280 <div class="footer">
 281 <hr>
 282           Generated by GTK-Doc V1.18</div>
 283 </body>
 284 </html>