Rewrite the CMake FAQ in restructured, as an introduction

doc/buildsystem/CMakeLists.txt

-#dune_add_latex_document(buildsystem.tex FATHER_TARGET doc DEFAULT_PDF INPUTS ../Makefile.am ../../configure.ac ../example.opts)
-#create_doc_install(${CMAKE_CURRENT_BINARY_DIR}/buildsystem.pdf ${CMAKE_INSTALL_DOCDIR}/buildsystem)
-#
-#dune_add_latex_document(cmakefaq.tex FATHER_TARGET doc DEFAULT_PDF)
-#create_doc_install(${CMAKE_CURRENT_BINARY_DIR}/cmakefaq.pdf ${CMAKE_INSTALL_DOCDIR}/buildsystem)
+dune_add_latex_document(buildsystem.tex FATHER_TARGET doc DEFAULT_PDF INPUTS ../Makefile.am ../../configure.ac ../example.opts)
+create_doc_install(${CMAKE_CURRENT_BINARY_DIR}/buildsystem.pdf ${CMAKE_INSTALL_DOCDIR}/buildsystem)
 
-dune_cmake_sphinx_doc(PATHS ${CMAKE_SOURCE_DIR}/cmake/modules)
+# Also always build the CMake API documentation in dune-common
+dune_cmake_sphinx_doc()

doc/buildsystem/dune-common.rst

-Some interesting question
-=========================
+.. _whatis:
 
-and its answer.
+What is CMake anyway?
+=====================
+
+CMake...
+
+- is an open source buildsystem tool developed at KITware.
+- offers a one-tool-solution to all building tasks, like configuring, building, linking, testing and packaging.
+- is a build system generator: It supports a set of backends called ``generators''
+- is portable
+- is controlled by ONE rather simple language
+
+Dune got support for CMake in version 2.3 alongside the old Autotools build system. It got the default in the
+2.4 release. After that release, the Autotools build system will be removed from the master branch.
+
+You can install cmake through your favorite package manager or downloading source code from
+`KITWare <http://www.cmake.org>`_
+The minimum required version to build Dune with CMake is 2.8.6.
+
+.. _howtouse:
+How do I use Dune with CMake?
+=============================
+
+As with the Autotools, the build process is controlled by the script :code:`dunecontrol`, located in :code:`dune-common/bin`.
+There is a compatibility layer that will translate all the configure flags from your opts file into the corresponding
+CMake flags. While this is a great tool to determine how to do the transition, in the long run you should switch to
+a CMake-only approach.
+
+:code:`dunecontrol` will pickup the variable :code:`CMAKE_FLAGS` from your opts file and use it as command line options for
+any call to CMake. There, you can define variables for the configure process with CMakes :code:`-D` option; just as
+with the C pre-processor.
+
+The most important part of the configure flags is to tell the build system where to look for external libraries.
+You can browse the :ref:`input variables` section of this documentation for a list of variables that are picked up
+by the Dune CMake build system.
+
+.. _whatfiles:
+
+What files in a dune module belong to the CMake build system?
+=============================================================
+
+Every directory in a project contains a file called :code:`CMakeLists.txt`, which is written in the CMake language.
+You can think of these as a distributed configure script. Upon configure, the top-level :code:`CMakeLists.txt` is executed.
+Whenever an :ref:`add_subdirectory` command is encountered, the :code:`CMakeLists.txt` file of that sub-directory is executed.
+The top-level :code:`CMakeLists.txt` file is special, because it sets up the entire Dune module correctly. You should not delete the
+auto-generated parts of it.
+
+Additionally, a Dune module can export some cmake modules. A cmake module is a file that contains one or
+more build system macros meant for downstream use. If a module provides modules, they can be found in
+the subfolder :code:`cmake/modules`. The module :code:`dune-foo/cmake/modules/DuneFooMacros.cmake` in a module
+:code:`dune-foo` is special however: Its contents are always executed when configuring the module
+:code:`dune-foo` or any other Dune module, that requires or suggests the module :code:`dune-foo`.
+This is the perfect place to put your checks for external packages, see below.
+
+The file :code:`config.h.cmake` defines a template for the section of :code:`config.h`, that is generated by the module.
+
+The file :code:`stamp-regenerate-config-h` also belongs to the CMake build system.
+You can trigger regeneration of :code:`config.h` by touching it.
+
+.. _porting:
+
+How do I port an existing module?
+=================================
+
+There is multiple approaches to this:
+
+- First, check :ref:`enable` and decide whether such simple approach is sufficient for your project.
+- There is the python script :code:`dune-common/bin/am2cmake.py`, which automatically generates :code:`CMakeLists.txt`'s
+  from its :code:`Makefile.am` counterparts. While this works fine, for many modules the resulting files look very
+  autotoolish and are often too complicated.
+- Copy the top-level :code:`CMakeLists.txt` file from a freshly generated Dune module (you still need to adjust the
+  project name to have it match the module name) and write all other :code:`CMakeLists.txt` by hand. This sounds
+  cumbersome, but its actually not very much work if you read below advices and have the online documentation at hand.
+
+In order to write your own :code:`CMakeLists.txt` files you should be aware of the following basic commands of the CMake
+language:
+
+- :ref:`add_subdirectory` for recursively adding subdirectories
+- :ref:`add_executable` to add some exectuable programs
+- :ref:`add_test` to register tests to the test suite.
+- :ref:`install` to mark files for installation.
+
+For futher commands, browse this documentation.
+
+If your module requires any other packages than the dune modules listed in your :code:`dune.module` file, you should
+also use the command :ref:`find_package` in the module :code:`dune-foo/cmake/modules/DuneFooMacros.cmake`
+(as mentioned in :ref:`whatfiles`). How to do this with external packages not yet supported by Dune is
+covered in :ref:`external`
+
+.. _flags:
+
+How do I modify the flags and linked libraries of a given target?
+=================================================================
+
+Again, there are multiple ways to do this. The Dune build system offers macros to make this task as
+easy as possible. For each external module, there is a macro :code:`add_dune_*_flags`. Those macros should
+cover most flags. Example usage:
+
+.. code-block:: cmake
+
+    add_executable(foo foo.cc)
+    add_dune_umfpack_flags(foo)
+    add_dune_mpi_flags(foo)
+
+There is also the macro :ref:`add_dune_all_flags`, which uses the same flag registry mechanism then the simplfied
+build system in section :ref:`simplified`.
+
+If you want to fully control the configuration of the targets, you can do so. Build system entities such
+as targets, directories and tests do have so called properties in CMake. You can access and modify those
+properties via the commands :code:`get_property` and :code:`set_property`. You can for example use those
+to modify a targets :code:`COMPILE_DEFINITIONS` or :code:`INCLUDE_DIRECTORIES` property:
+
+.. code-block:: cmake
+
+    add_executable(foo foo.cc)
+    set_property(TARGET foo APPEND PROPERTY COMPILE_DEFINITIONS <somedefinition>)
+    set_property(TARGET foo APPEND PROPERTY INCLUDE_DIRECTORIES <somepath>)
+
+For a full list of properties, check the manual:
+
+.. code-block:: bash
+
+    cmake --help-property-list
+
+Manually linking libraries can be done through the :code:`target_link_libraries` command instead of manually
+tweaking properties.
+
+.. _external:
+
+How do I link against external libraries, that are not checked for by Dune?
+===========================================================================
+
+While there might be many solutions that make your application work, there is only one clean solution to this: You have
+to provide a find module for the package. A find module is a CMake module that follows a specific naming scheme: For
+an external package called :code:`SomePackage` it is called :code:`FindSomePackage.cmake`. Note that CMake
+treats package names case sensitive. If CMake encounters a :code:`find_package(SomePackage)` line, it searches
+its module include paths for this find module. A good read to get started writing a find module is
+`this page <http://www.cmake.org/Wiki/CMake:How_To_Find_Libraries>`_ in the CMake wiki.
+
+Depending on how common your external package is, you may not even need to write the find module on your own.
+You can have a look at the list of find modules shipped by CMake or simply search the
+internet for the module name and profit from other open-source project's work.
+
+It is considered good style to also provide a macro :code:`add_dune_somepackage_flags`.
+
+.. _outofsource:
+
+What is an out-of-source build?
+===============================
+
+An out-of-source build does leave the version-controlled source tree untouched and puts all files that are
+generated by the build process into a different directory -- the build directory. The build directory does mirror
+your source tree's structure as seen in the following. Assume the following source directory structure:
+
+::
+
+   dune-foo/
+     CMakeLists.txt
+     dune/
+       foo/
+         CMakeLists.txt
+     src/
+       CMakeLists.txt
+
+::
+
+The generated build directory will have the following structure, where the directory :code:`build-cmake`
+is a subdirectory of the source directory:
+
+::
+
+  build-cmake/
+    Makefile
+    dune/
+      foo/
+        Makefile
+    src/
+      Makefile
+
+::
+
+Using the :code:`Unix Makefiles` generator, your Makefiles are generated in the build tree, so that is where you
+have to call :code:`make`. There are multiple advantages with this approach, such as a clear separation between
+version controlled and generated files and you can have multiple out-of-source builds with different configurations
+at the same time.
+
+Out-of-source builds are the default with CMake. In-source builds are strongly discouraged.
+
+By default, a subfolder :code:`build-cmake` is generated within each dune module and is used as a build directory.
+You can customize this folder through the :code:--builddir: option of :code:`dunecontrol`. Give an absolute path to
+the :code:`--builddir` option, you will get something like this:
+
+::
+
+  build/
+    dune-common/
+      Makefile
+    dune-foo/
+      Makefile
+
+::
+
+So, instead of one build directory in every dune module, you will be able to collect all build directories in one
+directory. This makes it much easier to have multiple build directories and to remove build directories.
+
+.. _simplified:
+
+What is the new simplified build system and how do I use it?
+============================================================
+
+Dune offers a simplified build system, where all flags are added to all targets and all libraries are linked to all targets. You can enable the feature
+by calling :ref:`dune_enable_all_packages` in the top-level :code:`CMakeLists.txt` file of your project, before you add any subdirectories.
+
+This will modify all targets in the directory of the :code:`CMakeLists.txt`, where you put this, and also in all
+subdirectories. The compile flags for all found external packages are added to those targets and the target is
+linked against all found external libraries.
+
+To use this while using custom external packages, you have to register your flags to the mechansim.
+Also, some special care has to be given, if your module does build one or more library which targets within the module do link against.
+
+Carefully read the followinf documentation in those cases:
+
+* :ref:`dune_enable_all_packages`
+* :ref:`dune_register_package_flags`
+* :ref:`dune_library_add_sources`
+
+.. _compiler:
+
+How do I change my compiler and compiler flags?
+===============================================
+
+In general, there are multiple ways to do this:
+
+* Setting the CMake variables :ref:`CMAKE_C_COMPILER` and :ref:`CMAKE_CXX_COMPILER` resp. from the opts file
+* Setting those variables within the project with the :code:`set` command
+* Setting the environment variables :code:`CC`, :code:`CXX` etc.
+
+The first option is the recommended way. Whenever you change your compiler, you should delete all build
+directories. For some CMake versions, there is a known CMake bug, that requires you to give an absolute path
+to your compiler, but Dune will issue a warning, if you violate that.
+
+You can modify your default compiler flags by setting the variables
+:ref:`CMAKE_C_FLAGS` and :ref:`CMAKE_CXX_FLAGS` in your opts file.
+
+.. _symlink:
+
+How should I handle ini and grid files in an out-of-source-build setup?
+=======================================================================
+
+Such files are under version control, but they are needed in the build directory.
+There are some CMake functions targetting this issue:
+
+* :ref:`dune_symlink_to_source_tree`
+* :ref:`dune_symlink_to_source_files`
+* :ref:`dune_add_copy_command`
+* :ref:`dune_add_copy_dependency`
+* :ref:`dune_add_copy_target`
+
+The simplest way to solve the problem is to set the variable :ref:`DUNE_SYMLINK_TO_SOURCE_TREE` to your opts file.
+This will execute :ref:`dune_symlink_to_source_tree` in your top-level :code:`CMakeLists.txt`. This will add a symlink
+:code:`src_dir` to all subdirectories of the build directory, which points to the corresponding directory of the source
+tree. This will only work on platforms that support symlinking.
+
+.. _ides:
+
+How do I use CMake with IDEs?
+=============================
+
+As already said, CMake is merely a build system generator with multiple backends (called a generator). Using IDEs requires
+a different generator. Check :code:`cmake --help` for a list of generators. You can then add the :code:`-G` to the :code:`CMAKE_FLAGS` in your opts file.
+Note that the generator name has to match character by character, including case and spaces.
+
+.. _cxxflags:
+
+I usually modify my CXXFLAGS upon calling make. How can I do this in CMake?
+===========================================================================
+
+This violates the CMake philosophy and there is no clean solution to achieve it. The CMake-ish solution would be
+to have for each configuration one out-of-source build. We have nevertheless implemented a workaround. It can be enable
+by setting the variable :ref:`ALLOW_CXXFLAGS_OVERWRITE` in your opts file. You can then type:
+
+.. code-block: bash
+   make CXXFLAGS="<your flags>" <target>
+
+Furthermore any C pre-processor variable of the form :code:`-DVAR=<value>` can be overloaded on the command line
+and the grid type can be set via :code:`GRIDTYPE="<grid type>"`.
+
+Note this only works with generators that are based on Makefiles and several Unix tools like bash must be
+available.
+
+.. _test:
+
+How do I run the test suite from CMake?
+=======================================
+
+The built-in target to run the tests is called :code:`test` instead of Autotools' :code:`check`.
+It is a mere wrapper around CMake's own testing tool CTest. You can check :code:`ctest --help`
+for a lot of useful options, such as choosing the set of tests to be run by matching regular expressions or
+showing the output of failed tests.
+
+Although this is not the CMake-ish way, :code:`make test` also builds the tests before executing them.
+This behavior will change in the near future.
+
+.. disable:
+
+Can I disable an external dependency?
+=====================================
+
+To disable an external dependency :code:`Foo`, add
+
+.. code-block:
+   -DCMAKE_DISABLE_FIND_PACKAGE_Foo=TRUE
+
+to your opts file. The name of the dependency is case sensitive but there is no canonical naming
+scheme. See the output of configure to get the right name.
+
+Make sure to not use cached configure results by deleting the cache file or the build directory, cf.
+:ref:`troubleshoot`.
+
+.. _parallel:
+
+How do I switch between parallel and sequential builds?
+=======================================================
+
+Dune builds with CMake are parallel if and only if MPI is found. To have a sequential build despite an
+installed MPI library, you have to explicitly disable the corresponding find module by setting
+
+.. code-block:
+   -DCMAKE_DISABLE_FIND_PACKAGE_MPI=TRUE
+
+in the :ref:`CMAKE_FLAGS` of your opts file, as described in section :ref:`disable`.
+
+.. _headercheck:
+
+Why is it not possible anymore to do make headercheck?
+======================================================
+
+The headercheck feature has been disabled by default. You can enable it by setting the CMake variable :ref:`ENABLE_HEADERCHECK`
+ through your opts file. This step has been necessary, because of the large amount of additional file the headercheck adds to the
+build directory. A better implementation has not been found yet, because it simply does not fit the CMake philosophy.
+
+.. _troubleshoot:
+
+How do I troubleshoot?
+======================
+
+CMake caches aggressively which makes it bad at recognizing changed configurations.
+To trigger a fresh run of configure, you can delete the :code:`CMakeCache.txt` file from
+the build directory and maybe save some compilation time afterward.
+
+Whenever you experience any problems, your first step should be to delete all build directories. Nice trick:
+
+.. code-block: bash
+   dunecontrol exec rm -rf build-cmake
+
+This will remove all build directories from all DUNE modules.
+
+Later on you can get an error log from the file :code:`CMakeError.log` in the :code:`CMakeFiles`
+subdirectory of your build directory. This is what you should send to the mailing list alongside the
+description of your setup and efforts to help us help you.
+
+Where can I get help?
+=====================
+
+The CMake manual is available on the command line:
+
+* :code:`cmake --help-command-list`
+* :code:`cmake --help-command <command>`
+* :code:`cmake --help-property-list`
+* :code:`cmake --help-property <property>`
+* :code:`cmake --help-module-list`
+* :code:`cmake --help-module <module>`
+
+To get help on which variables are picked up by CMake, there is a CMake wiki page collecting them.
+Of course, there is also Google, StackOverflow and the CMake Mailing list (archive).
+For problems specific to DUNE's build system, ask on our mailing lists.