Mercurial > thymian

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