176 lines
6.5 KiB
TeX
176 lines
6.5 KiB
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 ;
|
|
\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}
|