From aa4d426b4d3527d7e166df1a05058c9a4a0f6683 Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Fri, 30 Apr 2021 00:33:56 +0200 Subject: initial/final commit --- vmime-master/doc/book/building.tex | 175 +++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 vmime-master/doc/book/building.tex (limited to 'vmime-master/doc/book/building.tex') diff --git a/vmime-master/doc/book/building.tex b/vmime-master/doc/book/building.tex new file mode 100644 index 0000000..9feeedc --- /dev/null +++ b/vmime-master/doc/book/building.tex @@ -0,0 +1,175 @@ +\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} -- cgit v1.2.3