Mercurial > thymian

annotate 3rdparty/vmime/doc/book/building.tex @ 0:a4671277546c tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
created the repository for the thymian project
author ferencd
date Tue, 17 Aug 2021 11:19:54 +0200
parents
children
rev   line source
ferencd@0 1 \label{chapter_building}
ferencd@0 2 \chapter{Building and Installing VMime}
ferencd@0 3
ferencd@0 4 % ============================================================================
ferencd@0 5 \section{Introduction}
ferencd@0 6
ferencd@0 7 If no pre-build packages of VMime is available for your system, or if for some
ferencd@0 8 reason you want to compile it yourself from scratch, this section will guide
ferencd@0 9 you through the process.
ferencd@0 10
ferencd@0 11 % ============================================================================
ferencd@0 12 \section{What you need}
ferencd@0 13
ferencd@0 14 To build VMime from the sources, you will need the following:
ferencd@0 15
ferencd@0 16 \begin{itemize}
ferencd@0 17 \item a working C++ compiler with good STL implementation and also a good
ferencd@0 18 support for templates (for example, \href{http://gcc.gnu.org/}{GNU GCC}) ;
ferencd@0 19 \item \href{http://www.cmake.org/}{CMake} build system ;
ferencd@0 20 \item either \href{http://www.icu-project.org}{ICU library} or an usable
ferencd@0 21 {\vcode iconv()} implementation (see
ferencd@0 22 \href{http://www.gnu.org/software/libiconv/}{libiconv of GNU Project}) ;
ferencd@0 23 \item the \href{http://www.gnu.org/software/gsasl/}{GNU SASL Library} if you
ferencd@0 24 want SASL\footnote{Simple Authentication and Security Layer} support ;
ferencd@0 25 \item either the \href{http://www.openssl.org}{OpenSSL library} or the
ferencd@0 26 \href{http://www.gnu.org/software/gnutls/}{GNU TLS Library} if you
ferencd@0 27 want SSL and TLS\footnote{Transport Layer Security} support ;
ferencd@0 28 \item the \href{http://www.boost.org}{Boost C++ library} if you are not using
ferencd@0 29 C++11 (or your compiler does not support it), for {\vcode shared\_ptr<>}.
ferencd@0 30 \end{itemize}
ferencd@0 31
ferencd@0 32 % ============================================================================
ferencd@0 33 \section{Obtaining source files}
ferencd@0 34
ferencd@0 35 You can download a package containing the source files of the latest release
ferencd@0 36 of the VMime library from the \href{http://www.vmime.org/}{VMime web site}.
ferencd@0 37
ferencd@0 38 You can also obtain the current development version from the Git repository,
ferencd@0 39 which is currently hosted at GitHub. It can be checked out through anonymous
ferencd@0 40 access with the following instruction:
ferencd@0 41
ferencd@0 42 \begin{verbatim}
ferencd@0 43 git clone git://github.com/kisli/vmime
ferencd@0 44 \end{verbatim}
ferencd@0 45
ferencd@0 46 % ============================================================================
ferencd@0 47 \section{Compiling and installing}
ferencd@0 48
ferencd@0 49 There are two possibilities for compiling VMime: using SCons building system,
ferencd@0 50 or using CMake.
ferencd@0 51
ferencd@0 52 SCons is only used for development purposes, and so it is recommended that you
ferencd@0 53 use CMake to build the project as it is a more portable solution, and is
ferencd@0 54 likely to work out-of-the-box on your computer. Thus, we will not describe
ferencd@0 55 the process of compiling VMime using SCons here.
ferencd@0 56
ferencd@0 57 CMake is an open source, cross-platform build system. It will generate all
ferencd@0 58 build scripts required to compile VMime on your platform.
ferencd@0 59
ferencd@0 60 First, from the directory where you extracted the tarball or checked out
ferencd@0 61 the sources, run {\vcode cmake} with the {\vcode -G} argument corresponding
ferencd@0 62 to your platform. For example, if you are on a Unix-compatible platform (like
ferencd@0 63 GNU/Linux or MacOS), type:
ferencd@0 64
ferencd@0 65 \begin{verbatim}
ferencd@0 66 $ cmake -G "Unix Makefiles"
ferencd@0 67 \end{verbatim}
ferencd@0 68
ferencd@0 69 This will perform some tests on your system to check for libs installed
ferencd@0 70 and some platform-specific includes. It will then create a Makefile in
ferencd@0 71 the root directory of VMime.
ferencd@0 72
ferencd@0 73 \vnote{Delete the {\vcode CMakeCache.txt} file if something changed on your
ferencd@0 74 system, as CMake may cache some values to speed up things.}
ferencd@0 75
ferencd@0 76 This will also create a file named {\vcode config.hpp} in the {\vcode vmime/}
ferencd@0 77 directory, with the parameters detected for your platform. You should not
ferencd@0 78 modify this file directly. Instead, you can run again {\vcode cmake} and
ferencd@0 79 specify your own defines on the command line.
ferencd@0 80
ferencd@0 81 For example, to force using OpenSSL library instead of GnuTLS for TLS
ferencd@0 82 support, type:
ferencd@0 83
ferencd@0 84 \begin{verbatim}
ferencd@0 85 $ cmake -G "Unix Makefiles" -DVMIME_TLS_SUPPORT_LIB=openssl
ferencd@0 86 \end{verbatim}
ferencd@0 87
ferencd@0 88 If you want to enable or disable some features in VMime, you can obtain some
ferencd@0 89 help by typing {\vcode cmake -L}. The defaults should be OK though. For a list
ferencd@0 90 of build options, you can also refer to section \ref{build-options}, page
ferencd@0 91 \pageref{build-options}.
ferencd@0 92
ferencd@0 93 For more information about using CMake, go to
ferencd@0 94 \href{http://www.cmake.org/}{the CMake web site}.
ferencd@0 95
ferencd@0 96 Next, you can start the compilation process:
ferencd@0 97
ferencd@0 98 \begin{verbatim}
ferencd@0 99 $ make
ferencd@0 100 \end{verbatim}
ferencd@0 101
ferencd@0 102 Please wait a few minutes will the compilation runs (you should have some time
ferencd@0 103 to have a coffee right now!). If you get errors during the compilation, be
ferencd@0 104 sure your system meet the requirements given at the beginning of the chapter.
ferencd@0 105 You can also try to get a newer version (from the Git repository, for example)
ferencd@0 106 or to get some help on VMime user forums.
ferencd@0 107
ferencd@0 108 If everything has been compiled successfully, you can install the library and
ferencd@0 109 the development files on your system:
ferencd@0 110
ferencd@0 111 \begin{verbatim}
ferencd@0 112 # make install
ferencd@0 113 \end{verbatim}
ferencd@0 114
ferencd@0 115 \vnote{you must do that with superuser rights (root) if you chose to install
ferencd@0 116 the library into the default location (ie: /usr/lib and /usr/include).}
ferencd@0 117
ferencd@0 118 Now, you are done! You can jump to the next chapter to know how to use VMime
ferencd@0 119 in your program...
ferencd@0 120
ferencd@0 121 % ============================================================================
ferencd@0 122 \section{\label{build-options}Build options}
ferencd@0 123
ferencd@0 124 Some options can be given to CMake to control the build:
ferencd@0 125
ferencd@0 126 \begin{table}[!ht]
ferencd@0 127 \noindent\begin{tabularx}{1.0\textwidth}{|l|X|}
ferencd@0 128 \hline
ferencd@0 129 {\bf Option name} &
ferencd@0 130 {\bf Description} \\
ferencd@0 131 \hline
ferencd@0 132 \hline
ferencd@0 133 VMIME\_BUILD\_SHARED\_LIBRARY &
ferencd@0 134 Set to ON to build a shared version (.so) of the library (default is ON). \\
ferencd@0 135 \hline
ferencd@0 136 VMIME\_BUILD\_STATIC\_LIBRARY &
ferencd@0 137 Set to ON to build a static version (.a) of the library (default is ON). \\
ferencd@0 138 \hline
ferencd@0 139 VMIME\_BUILD\_TESTS &
ferencd@0 140 Set to ON to build unit tests (default is OFF). \\
ferencd@0 141 \hline
ferencd@0 142 VMIME\_TLS\_SUPPORT\_LIB &
ferencd@0 143 Set to either "openssl" or "gnutls" to force using either OpenSSL or GNU TLS
ferencd@0 144 for SSL/TLS support (default depends on which libraries are available on
ferencd@0 145 your system). \\
ferencd@0 146 \hline
ferencd@0 147 VMIME\_CHARSETCONV\_LIB &
ferencd@0 148 Set to either "iconv", "icu" or "win" (Windows only) to force using iconv, ICU
ferencd@0 149 or Windows built-in API for converting between charsets (default value depends
ferencd@0 150 on which libraries are available on your system). \\
ferencd@0 151 \hline
ferencd@0 152 CMAKE\_BUILD\_TYPE &
ferencd@0 153 Set the build type: either "Release" or "Debug". In Debug build, optimizations
ferencd@0 154 are disabled and debugging information are enabled. \\
ferencd@0 155 \hline
ferencd@0 156 \end{tabularx}
ferencd@0 157 \caption{CMake build options}
ferencd@0 158 \end{table}