From 883fc0cc9f1b0953dd62cb77e7adf2e7d6e9e9aa Mon Sep 17 00:00:00 2001 From: Radovan Bast Date: Mon, 5 Oct 2015 15:24:38 +0200 Subject: [PATCH] update doc for developers --- doc/developers/bootstrap.rst | 26 ++++++++++++++------------ doc/developers/customizing-modules.rst | 21 +++++++++++++++++++-- doc/developers/example.rst | 11 +++++++---- doc/developers/updating-modules.rst | 8 ++++---- 4 files changed, 44 insertions(+), 22 deletions(-) diff --git a/doc/developers/bootstrap.rst b/doc/developers/bootstrap.rst index f414a8c..82259b0 100644 --- a/doc/developers/bootstrap.rst +++ b/doc/developers/bootstrap.rst @@ -15,7 +15,7 @@ infrastructure files which will be needed to build the project:: $ wget https://github.com/scisoft/autocmake/raw/master/update.py $ python update.py --self -On the MS Windows system, use the PowerShell wget-replacement:: +On the MS Windows system, you can use the PowerShell wget-replacement:: $ Invoke-WebRequest https://github.com/scisoft/autocmake/raw/master/update.py -OutFile update.py @@ -23,13 +23,14 @@ This creates (or updates) the following files (an existing ``autocmake.cfg`` is not overwritten by the script):: cmake/ - update.py # no need to edit - autocmake.cfg # edit this file + autocmake.cfg # edit this file + update.py # no need to edit lib/ - config.py # no need to edit - docopt.py # no need to edit + config.py # no need to edit + docopt/ + docopt.py # no need to edit -Note that all other listed files are overwritten (use version control!). +Note that all other listed files are overwritten (use version control). Generating the CMake infrastructure @@ -38,7 +39,7 @@ Generating the CMake infrastructure Now customize ``autocmake.cfg`` to your needs (see :ref:`autocmake_cfg`) and then run the ``update.py`` script which -creates ``CMakeLists.txt`` and ``setup.py``:: +creates ``CMakeLists.txt`` and ``setup.py`` in the target path:: $ python update.py .. @@ -46,12 +47,13 @@ The script also downloads external CMake modules specified in ``autocmake.cfg`` called ``downloaded/``:: cmake/ - update.py - autocmake.cfg + autocmake.cfg # edit this file + update.py # no need to edit lib/ - config.py - docopt.py - downloaded/ # contains CMake modules fetched from the web + config.py # no need to edit + docopt/ + docopt.py # no need to edit + downloaded/ # contains CMake modules fetched from the web Building the project diff --git a/doc/developers/customizing-modules.rst b/doc/developers/customizing-modules.rst index 41ff332..0f3066b 100644 --- a/doc/developers/customizing-modules.rst +++ b/doc/developers/customizing-modules.rst @@ -5,7 +5,7 @@ Customizing CMake modules The ``update.py`` script assembles modules listed in ``autocmake.cfg`` into ``CMakeLists.txt``. Those that are fetched from the web are placed inside -``downloaded/``. You have at least four options to customize downloaded CMake +``downloaded/``. You have several options to customize downloaded CMake modules: @@ -20,12 +20,29 @@ the least elegant solution since the customizations may be overwritten by the Adapt local copies of CMake modules ----------------------------------- -A better solution is to download the CMake modules that you wish you customize +A slightly better solution is to download the CMake modules that you wish you customize to a separate directory (e.g. ``custom/``) and source the customized CMake modules in ``autocmake.cfg``. Alternatively you can serve your custom modules from your own http server. +Fork and branch the CMake modules +--------------------------------- + +You can fork and branch the mainline Autocmake development and include +the branched customized versions. This will make it easier for you +to stay up-to-date with upstream development. + + +Overriding defaults +------------------- + +Some modules use interpolations to set defaults, see for instance +https://github.com/scisoft/autocmake/blob/master/modules/boost/boost.cmake#L33-L36. +These can be modified within ``autocmake.cfg``, e.g.: +https://github.com/scisoft/autocmake/blob/master/test/boost_libs/cmake/autocmake.cfg#L9 + + Create own CMake modules ------------------------ diff --git a/doc/developers/example.rst b/doc/developers/example.rst index b2517ca..9bebac6 100644 --- a/doc/developers/example.rst +++ b/doc/developers/example.rst @@ -35,7 +35,8 @@ Now from top-level our file tree looks like this:: | |-- autocmake.cfg | |-- lib | | |-- config.py - | | `-- docopt.py + | | `-- docopt + | | `-- docopt.py | `-- update.py `-- src |-- feature1.F90 @@ -46,6 +47,7 @@ Now we edit ``cmake/autocmake.cfg`` to look like this:: [project] name: hello + min_cmake_version: 2.8 [fc] source: https://github.com/scisoft/autocmake/raw/master/modules/fc.cmake @@ -57,7 +59,7 @@ Now we edit ``cmake/autocmake.cfg`` to look like this:: 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``. +support. The ``src.cmake`` module tells CMake to include a ``src/CMakeLists.txt``. We need to create ``src/CMakeLists.txt`` which can look like this:: add_executable( @@ -86,7 +88,8 @@ And this is what we got:: | | `-- autocmake_src.cmake | |-- lib | | |-- config.py - | | `-- docopt.py + | | `-- docopt + | | `-- docopt.py | `-- update.py |-- setup.py `-- src @@ -144,5 +147,5 @@ Now we are ready to build:: Excellent! But this was a lot of typing and file creating just to get a simple executable compiled!? Of course, all that could have been done with few command lines directly but now we have a cross-platform project and can extend it and -customize it and we got a front-end script and command-line parser for free. +customize it and we also got a front-end script and command-line parser for free. Now go out and explore more Autocmake modules and features. diff --git a/doc/developers/updating-modules.rst b/doc/developers/updating-modules.rst index 2fe446c..7eeca52 100644 --- a/doc/developers/updating-modules.rst +++ b/doc/developers/updating-modules.rst @@ -20,11 +20,11 @@ Sometimes you may want to avoid using the latest version of a CMake module and rather fetch an older version, for example with the hash ``abcd123``. To achieve this, instead of:: - [coverage] - source: https://github.com/scisoft/autocmake/raw/master/modules/code_coverage.cmake + [foo] + source: https://github.com/scisoft/autocmake/raw/master/modules/foo.cmake pin the version to ``abcd123`` (you do not need to specify the full Git hash, a unique beginning will do):: - [coverage] - source: https://github.com/scisoft/autocmake/raw/abcd123/modules/code_coverage.cmake + [foo] + source: https://github.com/scisoft/autocmake/raw/abcd123/modules/foo.cmake