\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 ;
\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}

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

First, extract the tarball or checkout the VMime source code into a directory
somewhere on your system, let's call it {\vcode /path/to/vmime-source}. Then,
create a build directory, which will contain all intermediate build files and
the final libraries, let's call it {\vcode /path/to/vmime-build}.

From the build directory, run {\vcode cmake} with the {\vcode -G} argument
corresponding to your platform/choice. For example, if you are on a
Unix-compatible platform (like GNU/Linux or MacOS) and want to use the
{\vcode make} utility for building, type:

\begin{verbatim}
   $ cd /path/to/vmime-build
   $ cmake -G "Unix Makefiles" /path/to/vmime-source
\end{verbatim}

CMake will perform some tests on your system to check for libs installed
and some platform-specific includes, and create all files needed for
compiling the project. Additionally, a {\vcode src/vmime/config.hpp} file
with the parameters detected for your system will be created.

Next, you can start the compilation process:

\begin{verbatim}
   $ cmake --build .
\end{verbatim}

Please wait a few minutes while 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 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{\label{custom-build}Customizing build}

You should not modify the {\vcode config.hpp} file directly. Instead, you
should run {\vcode cmake} again, and specify your build options 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=openssl
\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 a
complate list of build options, you can also refer to section
\ref{build-options}, page \pageref{build-options}. For more information about
using CMake, go to \href{http://www.cmake.org/}{the CMake web site}.

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

You can also use another build backend, like
Ninja\footnote{\url{https://ninja-build.org/}}, if you have it on your system:

\begin{verbatim}
   $ cd /path/to/vmime-build
   $ cmake -G Ninja /path/to/vmime-source
   $ ninja
   # ninja install
\end{verbatim}

To install VMime in a directory different from the default directory
({\vcode /usr} on GNU/Linux systems), set the
{\vcode CMAKE\_INSTALL\_PREFIX} option:

\begin{verbatim}
   $ cmake -DCMAKE_INSTALL_PREFIX=/opt/ ...
\end{verbatim}


% ============================================================================
\section{\label{build-options}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}