extend the autocmake.cfg doc

doc/developers/configuration.rst

@@ -10,9 +10,10 @@ below::
 
   [project]
   name: numgrid
+  min_cmake_version: 2.8
 
   [fc]
-  source: https://github.com/scisoft/autocmake/raw/master/modules/fc.cmake
+  source: https://github.com/scisoft/autocmake/raw/master/modules/fc_optional.cmake
 
   [cc]
   source: https://github.com/scisoft/autocmake/raw/master/modules/cc.cmake
@@ -24,6 +25,12 @@ below::
   source: https://github.com/scisoft/autocmake/raw/master/compilers/GNU.CXX.cmake
           https://github.com/scisoft/autocmake/raw/master/compilers/Intel.CXX.cmake
 
+  [rpath]
+  source: custom/rpath.cmake
+
+  [definitions]
+  source: https://github.com/scisoft/autocmake/raw/master/modules/definitions.cmake
+
   [coverage]
   source: https://github.com/scisoft/autocmake/raw/master/modules/code_coverage.cmake
 
@@ -60,6 +67,7 @@ The names of the other sections do not matter to Autocmake. You could name them
 
   [project]
   name: numgrid
+  min_cmake_version: 2.8
 
   [one]
   source: https://github.com/scisoft/autocmake/raw/master/modules/fc.cmake
@@ -84,14 +92,16 @@ As a minimal example we take an ``autocmake.cfg`` which only contains::
 
   [project]
   name: minime
+  min_cmake_version: 2.8
 
 First we make sure that the ``update.py`` script is up-to-date and that it has access
 to all libraries it needs::
 
   $ python update.py --self
 
+  - creating .gitignore
   - fetching lib/config.py
-  - fetching lib/docopt.py
+  - fetching lib/docopt/docopt.py
   - fetching update.py
 
 Good. Now we can generate ``CMakeLists.txt`` and ``setup.py``::
@@ -118,62 +128,132 @@ Excellent. Here is the generated ``CMakeLists.txt``::
       set(CMAKE_BUILD_TYPE "Debug")
   endif()
 
+  set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${PROJECT_SOURCE_DIR}/cmake/downloaded)
+
 This is the very bare minimum. Every Autocmake project will have at least these
 settings.
 
 And we also got a ``setup.py`` script (front-end to ``CMakeLists.txt``) with
 the following default options::
 
-  $ python setup.py -h
-
   Usage:
     ./setup.py [options] [<builddir>]
     ./setup.py (-h | --help)
 
   Options:
-    --type=<TYPE>              Set the CMake build type (debug, release, or relwithdeb) [default: release].
+    --type=<TYPE>                          Set the CMake build type (debug, release, or relwithdeb) [default: release].
-    --generator=<STRING>       Set the CMake build system generator [default: Unix Makefiles].
+    --generator=<STRING>                   Set the CMake build system generator [default: Unix Makefiles].
-    --show                     Show CMake command and exit.
+    --show                                 Show CMake command and exit.
-    --cmake-options=<OPTIONS>  Define options to CMake [default: None].
+    --cmake-executable=<CMAKE_EXECUTABLE>  Set the CMake executable [default: cmake].
-    <builddir>                 Build directory.
+    --cmake-options=<STRING>               Define options to CMake [default: ''].
-    -h --help                  Show this screen.
+    <builddir>                             Build directory.
+    -h --help                              Show this screen.
 
 That's not too bad although currently we cannot do much with this since there
 are no sources listed, no targets, hence nothing to build. We need to flesh out
-``CMakeLists.txt`` and this is what we will do in the next section.
+``CMakeLists.txt`` by extending ``autocmake.cfg``
+and this is what we will do in the next section.
 
 
 Assembling CMake plugins
 ------------------------
 
 Write me ...
+source
+several
+
+The preferred way to extend ``CMakeLists.txt`` is by editing ``autocmake.cfg``
+and using the ``source`` option::
+
+  [fc]
+  source: https://github.com/scisoft/autocmake/raw/master/modules/fc_optional.cmake
+
+This will download ``fc_optional.cmake`` and include it in ``CMakeLists.txt``.
+
+You can also include local CMake modules, e.g.::
+
+  [rpath]
+  source: custom/rpath.cmake
+
+It is also OK to include several modules at once::
+
+  [flags]
+  source: https://github.com/scisoft/autocmake/raw/master/compilers/GNU.CXX.cmake
+          https://github.com/scisoft/autocmake/raw/master/compilers/Intel.CXX.cmake
+
+The modules will be included in the same order as they appear in ``autocmake.cfg``.
 
 
 Fetching files without including them in CMakeLists.txt
 -------------------------------------------------------
 
-Write me ...
+Sometimes you want to fetch a file without including it in ``CMakeLists.txt``.
+This can be done with the ``fetch`` option.  This is for instance done by the
+``git_info.cmake`` module (see
+https://github.com/scisoft/autocmake/blob/master/modules/git_info/git_info.cmake#L10-L11).
+
+If ``fetch`` is invoked in ``autocmake.cfg``, then the fetched file is placed
+under ``downloaded/``.  If ``fetch`` is invoked from within a CMake module
+documentation (see below), then the fetched file is placed into the same
+directory as the CMake module file which fetches it.
 
 
 Generating setup.py options
 ---------------------------
 
-Write me ...
+Options for the ``setup.py`` script can be generated with the ``docopt``
+option. As an example, the following ``autocmake.cfg`` snippet will add a
+``--something`` flag::
+
+  [my_section]
+  docopt: --something Enable something [default: False].
+
+
+Setting CMake options
+---------------------
+
+Configure-time CMake options can be generated with the ``define`` option.
+Consider the following example which toggles the CMake variable
+``ENABLE_SOMETHING``::
+
+  [my_section]
+  docopt: --something Enable something [default: False].
+  define: '-DENABLE_SOMETHING={0}'.format(arguments['--something'])
 
 
 Setting environment variables
 -----------------------------
 
-Write me ...
+You can export environment variables at configure-time using the ``export``
+option. Consider the following example::
+
+  [cc]
+  docopt: --cc=<CC> C compiler [default: gcc].
+          --extra-cc-flags=<EXTRA_CFLAGS> Extra C compiler flags [default: ''].
+  export: 'CC=%s' % arguments['--cc']
+  define: '-DEXTRA_CFLAGS="%s"' % arguments['--extra-cc-flags']
 
 
 Auto-generating configurations from the documentation
 -----------------------------------------------------
 
-Write me ...
+To avoid a boring re-typing of boilerplate ``autocmake.cfg`` code it is possible
+to auto-generate configurations from the documentation. This is the case
+for many core modules which come with own options once you have sourced them.
+
+The lines following ``# autocmake.cfg configuration::`` are
+understood by the ``update.py`` script to infer ``autocmake.cfg`` code from the
+documentation. As an example consider
+https://github.com/scisoft/autocmake/blob/master/modules/cc.cmake#L20-L25.
+Here, ``update.py`` will infer the configurations for ``docopt``, ``export``,
+and ``define``.
 
 
 Overriding documented configurations
 ------------------------------------
 
-Write me ...
+Configurable documented defaults can be achieved using interpolations.  See for
+instance
+https://github.com/scisoft/autocmake/blob/master/modules/boost/boost.cmake#L33-L36.
+These can be modified within ``autocmake.cfg`` with a dictionary, e.g.:
+https://github.com/scisoft/autocmake/blob/master/test/boost_libs/cmake/autocmake.cfg#L9