ferencd@0: \label{chapter_building}
ferencd@0: \chapter{Building and Installing VMime}
ferencd@0: 
ferencd@0: % ============================================================================
ferencd@0: \section{Introduction}
ferencd@0: 
ferencd@0: If no pre-build packages of VMime is available for your system, or if for some
ferencd@0: reason you want to compile it yourself from scratch, this section will guide
ferencd@0: you through the process.
ferencd@0: 
ferencd@0: % ============================================================================
ferencd@0: \section{What you need}
ferencd@0: 
ferencd@0: To build VMime from the sources, you will need the following:
ferencd@0: 
ferencd@0: \begin{itemize}
ferencd@0: \item a working C++ compiler with good STL implementation and also a good
ferencd@0: support for templates (for example, \href{http://gcc.gnu.org/}{GNU GCC}) ;
ferencd@0: \item \href{http://www.cmake.org/}{CMake} build system ;
ferencd@0: \item either \href{http://www.icu-project.org}{ICU library} or an usable
ferencd@0: {\vcode iconv()} implementation (see
ferencd@0: \href{http://www.gnu.org/software/libiconv/}{libiconv of GNU Project}) ;
ferencd@0: \item the \href{http://www.gnu.org/software/gsasl/}{GNU SASL Library} if you
ferencd@0: want SASL\footnote{Simple Authentication and Security Layer} support ;
ferencd@0: \item either the \href{http://www.openssl.org}{OpenSSL library} or the
ferencd@0: \href{http://www.gnu.org/software/gnutls/}{GNU TLS Library} if you
ferencd@0: want SSL and TLS\footnote{Transport Layer Security} support ;
ferencd@0: \item the \href{http://www.boost.org}{Boost C++ library} if you are not using
ferencd@0: C++11 (or your compiler does not support it), for {\vcode shared\_ptr<>}.
ferencd@0: \end{itemize}
ferencd@0: 
ferencd@0: % ============================================================================
ferencd@0: \section{Obtaining source files}
ferencd@0: 
ferencd@0: You can download a package containing the source files of the latest release
ferencd@0: of the VMime library from the \href{http://www.vmime.org/}{VMime web site}.
ferencd@0: 
ferencd@0: You can also obtain the current development version from the Git repository,
ferencd@0: which is currently hosted at GitHub. It can be checked out through anonymous
ferencd@0: access with the following instruction:
ferencd@0: 
ferencd@0: \begin{verbatim}
ferencd@0:    git clone git://github.com/kisli/vmime
ferencd@0: \end{verbatim}
ferencd@0: 
ferencd@0: % ============================================================================
ferencd@0: \section{Compiling and installing}
ferencd@0: 
ferencd@0: There are two possibilities for compiling VMime: using SCons building system,
ferencd@0: or using CMake.
ferencd@0: 
ferencd@0: SCons is only used for development purposes, and so it is recommended that you
ferencd@0: use CMake to build the project as it is a more portable solution, and is
ferencd@0: likely to work out-of-the-box on your computer. Thus, we will not describe
ferencd@0: the process of compiling VMime using SCons here.
ferencd@0: 
ferencd@0: CMake is an open source, cross-platform build system. It will generate all
ferencd@0: build scripts required to compile VMime on your platform.
ferencd@0: 
ferencd@0: First, from the directory where you extracted the tarball or checked out
ferencd@0: the sources, run {\vcode cmake} with the {\vcode -G} argument corresponding
ferencd@0: to your platform. For example, if you are on a Unix-compatible platform (like
ferencd@0: GNU/Linux or MacOS), type:
ferencd@0: 
ferencd@0: \begin{verbatim}
ferencd@0:    $ cmake -G "Unix Makefiles"
ferencd@0: \end{verbatim}
ferencd@0: 
ferencd@0: This will perform some tests on your system to check for libs installed
ferencd@0: and some platform-specific includes. It will then create a Makefile in
ferencd@0: the root directory of VMime.
ferencd@0: 
ferencd@0: \vnote{Delete the {\vcode CMakeCache.txt} file if something changed on your
ferencd@0: system, as CMake may cache some values to speed up things.}
ferencd@0: 
ferencd@0: This will also create a file named {\vcode config.hpp} in the {\vcode vmime/}
ferencd@0: directory, with the parameters detected for your platform. You should not
ferencd@0: modify this file directly. Instead, you can run again {\vcode cmake} and
ferencd@0: specify your own defines on the command line.
ferencd@0: 
ferencd@0: For example, to force using OpenSSL library instead of GnuTLS for TLS
ferencd@0: support, type:
ferencd@0: 
ferencd@0: \begin{verbatim}
ferencd@0:    $ cmake -G "Unix Makefiles" -DVMIME_TLS_SUPPORT_LIB=openssl
ferencd@0: \end{verbatim}
ferencd@0: 
ferencd@0: If you want to enable or disable some features in VMime, you can obtain some
ferencd@0: help by typing {\vcode cmake -L}. The defaults should be OK though. For a list
ferencd@0: of build options, you can also refer to section \ref{build-options}, page
ferencd@0: \pageref{build-options}.
ferencd@0: 
ferencd@0: For more information about using CMake, go to
ferencd@0: \href{http://www.cmake.org/}{the CMake web site}.
ferencd@0: 
ferencd@0: Next, you can start the compilation process:
ferencd@0: 
ferencd@0: \begin{verbatim}
ferencd@0:    $ make
ferencd@0: \end{verbatim}
ferencd@0: 
ferencd@0: Please wait a few minutes will the compilation runs (you should have some time
ferencd@0: to have a coffee right now!). If you get errors during the compilation, be
ferencd@0: sure your system meet the requirements given at the beginning of the chapter.
ferencd@0: You can also try to get a newer version (from the Git repository, for example)
ferencd@0: or to get some help on VMime user forums.
ferencd@0: 
ferencd@0: If everything has been compiled successfully, you can install the library and
ferencd@0: the development files on your system:
ferencd@0: 
ferencd@0: \begin{verbatim}
ferencd@0:    # make install
ferencd@0: \end{verbatim}
ferencd@0: 
ferencd@0: \vnote{you must do that with superuser rights (root) if you chose to install
ferencd@0: the library into the default location (ie: /usr/lib and /usr/include).}
ferencd@0: 
ferencd@0: Now, you are done! You can jump to the next chapter to know how to use VMime
ferencd@0: in your program...
ferencd@0: 
ferencd@0: % ============================================================================
ferencd@0: \section{\label{build-options}Build options}
ferencd@0: 
ferencd@0: Some options can be given to CMake to control the build:
ferencd@0: 
ferencd@0: \begin{table}[!ht]
ferencd@0: \noindent\begin{tabularx}{1.0\textwidth}{|l|X|}
ferencd@0: \hline
ferencd@0: 	{\bf Option name} &
ferencd@0: 	{\bf Description} \\
ferencd@0: \hline
ferencd@0: \hline
ferencd@0: VMIME\_BUILD\_SHARED\_LIBRARY &
ferencd@0: Set to ON to build a shared version (.so) of the library (default is ON). \\
ferencd@0: \hline
ferencd@0: VMIME\_BUILD\_STATIC\_LIBRARY &
ferencd@0: Set to ON to build a static version (.a) of the library (default is ON). \\
ferencd@0: \hline
ferencd@0: VMIME\_BUILD\_TESTS &
ferencd@0: Set to ON to build unit tests (default is OFF). \\
ferencd@0: \hline
ferencd@0: VMIME\_TLS\_SUPPORT\_LIB &
ferencd@0: Set to either "openssl" or "gnutls" to force using either OpenSSL or GNU TLS
ferencd@0: for SSL/TLS support (default depends on which libraries are available on
ferencd@0: your system). \\
ferencd@0: \hline
ferencd@0: VMIME\_CHARSETCONV\_LIB &
ferencd@0: Set to either "iconv", "icu" or "win" (Windows only) to force using iconv, ICU
ferencd@0: or Windows built-in API for converting between charsets (default value depends
ferencd@0: on which libraries are available on your system). \\
ferencd@0: \hline
ferencd@0: CMAKE\_BUILD\_TYPE &
ferencd@0: Set the build type: either "Release" or "Debug". In Debug build, optimizations
ferencd@0: are disabled and debugging information are enabled. \\
ferencd@0: \hline
ferencd@0: \end{tabularx}
ferencd@0: \caption{CMake build options}
ferencd@0: \end{table}