Updated doc on building with CMake.

1 files changed, 63 insertions, 44 deletions

diff --git a/doc/book/building.tex b/doc/book/building.tex
index 4f257404..415f707a 100644
--- a/doc/book/building.tex
+++ b/doc/book/building.tex
@@ -46,39 +46,62 @@ access with the following instruction:
 % ============================================================================
 \section{Compiling and installing}
 
-There are two possibilities for compiling VMime: using SCons building system,
-or using CMake.
+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.
 
-SCons is only used for development purposes, and so it is recommended that you
-use CMake to build the project as it is a more portable solution, and is
-likely to work out-of-the-box on your computer. Thus, we will not describe
-the process of compiling VMime using SCons here.
+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}.
 
-CMake is an open source, cross-platform build system. It will generate all
-build scripts required to compile VMime on your platform.
+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:
 
-First, from the directory where you extracted the tarball or checked out
-the sources, run {\vcode cmake} with the {\vcode -G} argument corresponding
-to your platform. For example, if you are on a Unix-compatible platform (like
-GNU/Linux or MacOS), 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 -G "Unix Makefiles"
+   $ cmake --build .
 \end{verbatim}
 
-This will perform some tests on your system to check for libs installed
-and some platform-specific includes. It will then create a Makefile in
-the root directory of VMime.
+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:
 
-\vnote{Delete the {\vcode CMakeCache.txt} file if something changed on your
-system, as CMake may cache some values to speed up things.}
+\begin{verbatim}
+   # make install
+\end{verbatim}
 
-This will also create a file named {\vcode config.hpp} in the {\vcode vmime/}
-directory, with the parameters detected for your platform. You should not
-modify this file directly. Instead, you can run again {\vcode cmake} and
-specify your own defines on the command line.
+\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).}
 
-For example, to force using OpenSSL library instead of GnuTLS for TLS
+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}
@@ -86,37 +109,33 @@ support, type:
 \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 list
-of build options, you can also refer to section \ref{build-options}, page
-\pageref{build-options}.
+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}.
 
-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.}
 
-Next, you can start the compilation process:
+You can also use another build backend, like
+Ninja\footnote{\url{https://ninja-build.org/}}, if you have it on your system:
 
 \begin{verbatim}
-   $ make
+   $ cd /path/to/vmime-build
+   $ cmake -G Ninja /path/to/vmime-source
+   $ ninja
+   # ninja install
 \end{verbatim}
 
-Please wait a few minutes will 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 has been compiled successfully, you can install the library and
-the development files on your system:
+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}
-   # make install
+   $ cmake -DCMAKE_INSTALL_PREFIX=/opt/ ...
 \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{build-options}Build options}