add hello world example

doc/developers/configuration.rst

@@ -90,11 +90,19 @@ to all libraries it needs::
 
   $ python update.py --self
 
+  - fetching lib/config.py
+  - fetching lib/docopt.py
+  - fetching update.py
+
 Good. Now we can generate ``CMakeLists.txt`` and ``setup.py``::
 
   $ python update ..
 
-Here is the generated ``CMakeLists.txt``::
+  - parsing autocmake.cfg
+  - generating CMakeLists.txt
+  - generating setup.py
+
+Excellent. Here is the generated ``CMakeLists.txt``::
 
   # set minimum cmake version
   cmake_minimum_required(VERSION 2.8 FATAL_ERROR)
@@ -110,9 +118,11 @@ Here is the generated ``CMakeLists.txt``::
       set(CMAKE_BUILD_TYPE "Debug")
   endif()
 
-This is the very minimum. Every project will have at least these settings.
+This is the very bare minimum. Every Autocmake project will have at least these
+settings.
 
-And we also got a ``setup.py`` script with the following default options::
+And we also got a ``setup.py`` script (front-end to ``CMakeLists.txt``) with
+the following default options::
 
   $ python setup.py -h
 
@@ -129,7 +139,7 @@ And we also got a ``setup.py`` script with the following default options::
     -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, no nothing. We need to flesh out
+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.
 
 

doc/developers/example.rst

@@ -3,4 +3,142 @@
 Example Hello World project
 ===========================
 
-Write me ...
+This is a brief example for the busy and impatient programmer. For a longer
+tour please see :ref:`autocmake_cfg`.
+
+We start with a mixed Fortran-C project with the following sources::
+
+  feature1.F90
+  feature2.c
+  main.F90
+
+First thing we do is to create a directory ``src/`` and we move all sources
+there. This is not necessary for Autocmake but it is a generally good practice::
+
+  .
+  `-- src
+      |-- feature1.F90
+      |-- feature2.c
+      `-- main.F90
+
+Now we create ``cmake/`` and fetch ``update.py``::
+
+  $ mkdir cmake
+  $ cd cmake/
+  $ wget https://raw.githubusercontent.com/scisoft/autocmake/master/update.py
+  $ python update.py --self
+
+Now from top-level our file tree looks like this::
+
+  .
+  |-- cmake
+  |   |-- autocmake.cfg
+  |   |-- lib
+  |   |   |-- config.py
+  |   |   `-- docopt.py
+  |   `-- update.py
+  `-- src
+      |-- feature1.F90
+      |-- feature2.c
+      `-- main.F90
+
+Now we edit ``cmake/autocmake.cfg`` to look like this::
+
+  [project]
+  name: hello
+
+  [fc]
+  source: https://github.com/scisoft/autocmake/raw/master/modules/fc.cmake
+
+  [cc]
+  source: https://github.com/scisoft/autocmake/raw/master/modules/cc.cmake
+
+  [src]
+  source: https://github.com/scisoft/autocmake/raw/master/modules/src.cmake
+
+What we have specified here is the project name and that we wish Fortran and C
+support. The ``[src]`` module tells CMake to include a ``src/CMakeLists.txt``.
+We need to create ``src/CMakeLists.txt`` which can look like this::
+
+  add_executable(
+      hello.x
+      main.F90
+      feature1.F90
+      feature2.c
+      )
+
+We wrote that we want to get an executable "hello.x" built from our sources.
+
+Now we have everything to generate ``CMakeLists.txt`` and ``setup.py``::
+
+  $ cd cmake
+  $ python update ..
+
+And this is what we got::
+
+  .
+  |-- CMakeLists.txt
+  |-- cmake
+  |   |-- autocmake.cfg
+  |   |-- downloaded
+  |   |   |-- autocmake_cc.cmake
+  |   |   |-- autocmake_fc_optional.cmake
+  |   |   `-- autocmake_src.cmake
+  |   |-- lib
+  |   |   |-- config.py
+  |   |   `-- docopt.py
+  |   `-- update.py
+  |-- setup.py
+  `-- src
+      |-- CMakeLists.txt
+      |-- feature1.F90
+      |-- feature2.c
+      `-- main.F90
+
+Now we are ready to build::
+
+  $ python setup.py --fc=gfortran --cc=gcc
+
+  FC=gfortran CC=gcc cmake -DEXTRA_FCFLAGS="''" -DENABLE_FC_SUPPORT="ON" -DEXTRA_CFLAGS="''" -DCMAKE_BUILD_TYPE=release -G "Unix Makefiles" None /home/user/example
+
+  -- The C compiler identification is GNU 4.9.2
+  -- The CXX compiler identification is GNU 4.9.2
+  -- Check for working C compiler: /usr/bin/gcc
+  -- Check for working C compiler: /usr/bin/gcc -- works
+  -- Detecting C compiler ABI info
+  -- Detecting C compiler ABI info - done
+  -- Detecting C compile features
+  -- Detecting C compile features - done
+  -- Check for working CXX compiler: /usr/bin/c++
+  -- Check for working CXX compiler: /usr/bin/c++ -- works
+  -- Detecting CXX compiler ABI info
+  -- Detecting CXX compiler ABI info - done
+  -- Detecting CXX compile features
+  -- Detecting CXX compile features - done
+  -- The Fortran compiler identification is GNU 4.9.2
+  -- Check for working Fortran compiler: /usr/bin/gfortran
+  -- Check for working Fortran compiler: /usr/bin/gfortran  -- works
+  -- Detecting Fortran compiler ABI info
+  -- Detecting Fortran compiler ABI info - done
+  -- Checking whether /usr/bin/gfortran supports Fortran 90
+  -- Checking whether /usr/bin/gfortran supports Fortran 90 -- yes
+  -- Configuring done
+  -- Generating done
+  -- Build files have been written to: /home/user/example/build
+
+     configure step is done
+     now you need to compile the sources:
+     $ cd build
+     $ make
+
+  $ cd build/
+  $ make
+
+  Scanning dependencies of target hello.x
+  [ 25%] Building Fortran object src/CMakeFiles/hello.x.dir/main.F90.o
+  [ 50%] Building Fortran object src/CMakeFiles/hello.x.dir/feature1.F90.o
+  [ 75%] Building C object src/CMakeFiles/hello.x.dir/feature2.c.o
+  [100%] Linking Fortran executable hello.x
+  [100%] Built target hello.x
+
+Excellent!