vmime/doc/book/building.tex

\label{chapter_building}
\chapter{Building and Installing VMime}

% ============================================================================
\section{Introduction}

If no pre-build packages of VMime is available for your system, or if for some
reason you want to compile it yourself from scratch, this section will guide
you through the process.

% ============================================================================
\section{What you need}

To build VMime from the sources, you will need the following:

\begin{itemize}
\item a working C++ compiler with good STL implementation and also a good
support for templates (for example, \href{http://gcc.gnu.org/}{GNU GCC}) ;
\item \href{http://www.cmake.org/}{CMake} build system ;
\item either \href{http://www.icu-project.org}{ICU library} or an usable
{\vcode iconv()} implementation (see
\href{http://www.gnu.org/software/libiconv/}{libiconv of GNU Project}) ;
\item the \href{http://www.gnu.org/software/gsasl/}{GNU SASL Library} if you
want SASL\footnote{Simple Authentication and Security Layer} support ;
\item either the \href{http://www.openssl.org}{OpenSSL library} or the
\href{http://www.gnu.org/software/gnutls/}{GNU TLS Library} if you
want SSL and TLS\footnote{Transport Layer Security} support ;
\item the \href{http://www.boost.org}{Boost C++ library} if you are not using
C++11 (or your compiler does not support it), for {\vcode shared\_ptr<>}.
\end{itemize}

% ============================================================================
\section{Obtaining source files}

You can download a package containing the source files of the latest release
of the VMime library from the \href{http://www.vmime.org/}{VMime web site}.

You can also obtain the current development version from the Git repository,
which is currently hosted at GitHub. It can be checked out through anonymous
access with the following instruction:

\begin{verbatim}
   git clone git://github.com/kisli/vmime
\end{verbatim}

% ============================================================================
\section{Compiling and installing}

There are two possibilities for compiling VMime: using SCons building system,
or using CMake.

SCons is only used for development purposes, and so it is recommended that you
use CMake to build the project as it is a more portable solution, and is
likely to work out-of-the-box on your computer. Thus, we will not describe
the process of compiling VMime using SCons here.

CMake is an open source, cross-platform build system. It will generate all
build scripts required to compile VMime on your platform.

First, from the directory where you extracted the tarball or checked out
the sources, run {\vcode cmake} with the {\vcode -G} argument corresponding
to your platform. For example, if you are on a Unix-compatible platform (like
GNU/Linux or MacOS), type:

\begin{verbatim}
   $ cmake -G "Unix Makefiles"
\end{verbatim}

This will perform some tests on your system to check for libs installed
and some platform-specific includes. It will then create a Makefile in
the root directory of VMime.

\vnote{Delete the {\vcode CMakeCache.txt} file if something changed on your
system, as CMake may cache some values to speed up things.}

This will also create a file named {\vcode config.hpp} in the {\vcode vmime/}
directory, with the parameters detected for your platform. You should not
modify this file directly. Instead, you can run again {\vcode cmake} and
specify your own defines on the command line.

For example, to force using OpenSSL library instead of GnuTLS for TLS
support, type:

\begin{verbatim}
   $ cmake -G "Unix Makefiles" -DVMIME_TLS_SUPPORT_LIB_IS_OPENSSL=ON \
                               -DVMIME_TLS_SUPPORT_LIB_IS_GNUTLS=OFF
\end{verbatim}

If you want to enable or disable some features in VMime, you can obtain some
help by typing {\vcode cmake -L}. The defaults should be OK though.

For more information about using CMake, go to
\href{http://www.cmake.org/}{the CMake web site}.

Next, you can start the compilation process:

\begin{verbatim}
   $ make
\end{verbatim}

Please wait a few minutes will the compilation runs (you should have some time
to have a coffee right now!). If you get errors during the compilation, be
sure your system meet the requirements given at the beginning of the chapter.
You can also try to get a newer version (from the Git repository, for example)
or to get some help on VMime user forums.

If everything has been compiled successfully, you can install the library and
the development files on your system:

\begin{verbatim}
   # make install
\end{verbatim}

\vnote{you must do that with superuser rights (root) if you chose to install
the library into the default location (ie: /usr/lib and /usr/include).}

Now, you are done! You can jump to the next chapter to know how to use VMime
in your program...

% ============================================================================
\section{Build options}

Some options can be given to CMake to control the build:

\begin{table}[!ht]
\noindent\begin{tabularx}{1.0\textwidth}{|l|X|}
\hline
	{\bf Option name} &
	{\bf Description} \\
\hline
\hline
VMIME\_BUILD\_SHARED\_LIBRARY &
Set to ON to build a shared version (.so) of the library (default is ON). \\
\hline
VMIME\_BUILD\_STATIC\_LIBRARY &
Set to ON to build a static version (.a) of the library (default is ON). \\
\hline
VMIME\_BUILD\_TESTS &
Set to ON to build unit tests (default is OFF). \\
\hline
VMIME\_TLS\_SUPPORT\_LIB &
Set to either "openssl" or "gnutls" to force using either OpenSSL or GNU TLS
for SSL/TLS support (default depends on which libraries are available on
your system). \\
\hline
VMIME\_CHARSETCONV\_LIB &
Set to either "iconv", "icu" or "win" (Windows only) to force using iconv, ICU
or Windows built-in API for converting between charsets (default value depends
on which libraries are available on your system). \\
\hline
CMAKE\_BUILD\_TYPE &
Set the build type: either "Release" or "Debug". In Debug build, optimizations
are disabled and debugging information are enabled. \\
\hline
\end{tabularx}
\caption{CMake build options}
\end{table}