update documentation regarding example projects

docs/Examples.rst

@@ -5,8 +5,69 @@ Examples
 In the ``/examples`` sub directory several C++ and Fortran example
 programs are placed.
 
+Projects
+--------
+
+CMake
+^^^^^
+
+In the ``/examples`` directory are two example CMake projects. One uses a
+separately installed (or at least compiled) ALL, and the other includes
+the library as a subdirectory and builds it along with the main project.
+
+When copying the example projects, make sure the symbolic links are still
+resolved. The example programs of the project are just linked from the
+examples, with the exception of ``ALL_test.cpp``. This program is
+modified, so different feature flags are used for VTK and Voronoi, to test
+external usage of these features. The change happens in the shell script
+building the project.
+
+In both cases, if VTK output is enabled, CMake must be able to find it. If
+it is not able to by default, or a specific version should be used, set
+VTK_DIR to the directory containing VTK's CMake configuration. For our
+test system, which uses VTK 7.1, this is the ``/lib/cmake/vtk-7.1``
+subdirectory of the install prefix of VTK.
+
+
+Package
+"""""""
+The example project using ``find_package`` is available in
+``/example/CMakeProject``. The full build steps are visible from
+``build_all.sh``, which first compiles the library and then the example
+project, after setting ``ALL_DIR`` (and ``VTK_DIR``).
+
+In general, it suffices to just use ``find_package(ALL 0.9)`` in your
+project's ``CMakeLists.txt`` and then link the corresponding executables
+against this using ``target_link_library(YOUR_TARGET PUBLIC ALL:ALL)``.
+The libraries targets are exported in the ``ALL::`` namespace. The Fortran
+module is then ``ALL::ALL_fortran``.
+
+
+Subdirectory
+""""""""""""
+This project includes the library directly in the source tree via
+``add_subdirectory``. To avoid cyclic symbolic links, this version does
+not run out of the box, since we need the source tree of the library as a
+subdirectory of the project's directory. So copy the contents of
+``/example/CMakeProjectSubdir``. The files assume the library to reside in
+the subdirectory ``all`` and, if VTK is enabled, the VTK installation
+in ``vtk_bin``. Also remember, that the symbolic links still resolve. Then
+you can just run CMake and the project, along with the library, will be
+build. This is also referenced in ``build_all.sh``.
+
+The targets you have to link your executables against are, however, ``ALL``
+or ``ALL_fortran`` respectively. The library is only namespaced if using
+the aforementioned ``find_package`` method. And some name collisions may
+therefore also occur. Using this method causes the library to be
+automatically be build, but also to be rebuild every time the build
+directory is cleaned.
+
+
+Programs
+--------
+
 ``ALL_test``
-------------
+^^^^^^^^^^^^
 MPI C++ code that generates a particle distribution over the domains. At
 program start the domains form an orthogonal decomposition of the cubic 3d
 system. Each domain has the same volume as each other domain. Depending
@@ -57,7 +118,7 @@ not already exist. The resulting output can be visualized with tools like
 ParaView or VisIt.
 
 ``ALL_test_f`` and ``ALL_test_f_obj``
--------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 The Fortran example provides a more basic version of the test program
 ``ALL_test``, as its main goal is to show the functionality of the Fortran
 interface. The code creates a basic uniform orthogonal domain
@@ -67,7 +128,7 @@ out the domain distribution of the start configuration and of the final
 configuration.
 
 ``ALL_Staggered`` and ``ALL_Staggered_f``
------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 These create a very simple load balancing situation with fixed load and
 domains placed along the z direction. The C++ and Fortran versions are
 functionally the same, so the differences between the interfaces can be