From 7c719d92fa705dd78b8c4bc6389f3e8cc02d4549 Mon Sep 17 00:00:00 2001 From: Radovan Bast Date: Fri, 31 Jul 2015 13:17:17 +0200 Subject: [PATCH] add hello world example --- doc/developers/configuration.rst | 18 +++- doc/developers/example.rst | 140 ++++++++++++++++++++++++++++++- 2 files changed, 153 insertions(+), 5 deletions(-) diff --git a/doc/developers/configuration.rst b/doc/developers/configuration.rst index 911e0a3..9cae737 100644 --- a/doc/developers/configuration.rst +++ b/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. diff --git a/doc/developers/example.rst b/doc/developers/example.rst index 50fbcf4..fe6ce8d 100644 --- a/doc/developers/example.rst +++ b/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!