Describe some CMake options

docs/source/install/index.rst

@@ -258,6 +258,44 @@ The commands above are equivalent to having run this command the first time:
     # Initial configuration in Debug mode with dynamic linking
     cmake .. -DCMAKE_BUILD_TYPE=Debug -DBUILD_SHARED_LIBS=ON
 
+CMAKE_BUILD_TYPE
+****************
+This option allows to set the compiler optimization level and debug
+information. The value and its effect are listed in the table below.
+
+================== ================================================================================================================
+ CMAKE_BUILD_TYPE   Effect
+================== ================================================================================================================
+ Release            ``-O3`` optimization level
+ RelWithDebInfo     ``-O2`` optimization level with ``-g`` flag for debug info
+ Debug              No optimization and `-g` flag for debug info; additional debugging flags: ``-fcheck=all -pedantic -fbacktrace``
+================== ================================================================================================================
+
+For best performance but longer compile time, use ``Release``. The next level,
+``RelWithDebInfo`` provides comparable performance and much faster compile
+time. Finally, use ``Debug`` during active development to catch any programming
+errors that would otherwise be handled by the compiler and to include debugging
+symbols so that the executables can be parsed by a debugger.
+
+This flag can be set with the following command:
+
+.. code-block:: bash
+
+    cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo
+
+CMAKE_INSTALL_PREFIX
+********************
+This flag sets the location of the compiled binaries when the build
+tool runs the ``install`` command. It should be a full path in a carefully
+chosen location. The binaries will be copied into ``include``, ``lib``,
+and ``bin`` subfolders under the value of this flag. The default is to
+install binaries within the repository in a folder called ``install``.
+
+This flag can be set with the following command:
+
+.. code-block:: bash
+
+    cmake .. -DCMAKE_INSTALL_PREFIX="/usr/local/"
 
 Setting the build tool
 ++++++++++++++++++++++