From 49d1652c984648c99cee9135dcec47447f8d2801 Mon Sep 17 00:00:00 2001 From: Radovan Bast Date: Sat, 28 May 2016 18:03:22 +0200 Subject: [PATCH] update parts of doc --- doc/developers/bootstrap.rst | 29 ++++++++++++-------------- doc/developers/configuration.rst | 2 +- doc/developers/customizing-modules.rst | 27 +++++++++++++++++------- doc/developers/example.rst | 2 +- 4 files changed, 34 insertions(+), 26 deletions(-) diff --git a/doc/developers/bootstrap.rst b/doc/developers/bootstrap.rst index d0d6918..e8e2798 100644 --- a/doc/developers/bootstrap.rst +++ b/doc/developers/bootstrap.rst @@ -19,41 +19,38 @@ On the MS Windows system, you can use the PowerShell wget-replacement:: $ Invoke-WebRequest https://github.com/coderefinery/autocmake/raw/master/update.py -OutFile update.py -This creates (or updates) the following files (an existing ``autocmake.cfg`` is +This creates (or updates) the following files (an existing ``autocmake.yml`` is not overwritten by the script):: cmake/ - autocmake.cfg # edit this file + autocmake.yml # edit this file update.py # no need to edit - lib/ - config.py # no need to edit - docopt/ - docopt.py # no need to edit + autocmake/ # no need to edit + ... # no need to edit -Note that all other listed files are overwritten (use version control). +Note that ``update.py`` and files under ``autocmake/`` +are overwritten (use version control). Generating the CMake infrastructure ----------------------------------- -Now customize ``autocmake.cfg`` to your needs -(see :ref:`autocmake_cfg`) +Now customize ``autocmake.yml`` to your needs +(see :ref:`autocmake_yml`) and then run the ``update.py`` script which creates ``CMakeLists.txt`` and a setup script in the target path:: $ python update.py .. -The script also downloads external CMake modules specified in ``autocmake.cfg`` to a directory +The script also downloads external CMake modules specified in ``autocmake.yml`` to a directory called ``downloaded/``:: cmake/ - autocmake.cfg # edit this file + autocmake.yml # edit this file update.py # no need to edit - lib/ - config.py # no need to edit - docopt/ - docopt.py # no need to edit - downloaded/ # contains CMake modules fetched from the web + autocmake/ # no need to edit + ... # no need to edit + downloaded/ # contains CMake modules fetched from the web Building the project diff --git a/doc/developers/configuration.rst b/doc/developers/configuration.rst index 7e91681..5496923 100644 --- a/doc/developers/configuration.rst +++ b/doc/developers/configuration.rst @@ -1,5 +1,5 @@ -.. _autocmake_cfg: +.. _autocmake_yml: Configuring autocmake.cfg ========================= diff --git a/doc/developers/customizing-modules.rst b/doc/developers/customizing-modules.rst index 30036df..fd6a37b 100644 --- a/doc/developers/customizing-modules.rst +++ b/doc/developers/customizing-modules.rst @@ -3,7 +3,7 @@ Customizing CMake modules ========================= -The ``update.py`` script assembles modules listed in ``autocmake.cfg`` into +The ``update.py`` script assembles modules listed in ``autocmake.yml`` into ``CMakeLists.txt``. Those that are fetched from the web are placed inside ``downloaded/``. You have several options to customize downloaded CMake modules: @@ -22,7 +22,7 @@ Adapt local copies of CMake modules 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 +modules in ``autocmake.yml``. Alternatively you can serve your custom modules from your own http server. @@ -34,19 +34,30 @@ the branched customized versions. This will make it easier for you to stay up-to-date with upstream development. -Overriding defaults +Overriding settings ------------------- -Some modules use interpolations to set defaults, see for instance -https://github.com/coderefinery/autocmake/blob/master/modules/boost/boost.cmake#L33-L36. -These can be modified within ``autocmake.cfg``, e.g.: -https://github.com/coderefinery/autocmake/blob/master/test/boost_libs/cmake/autocmake.cfg#L9 +If you source a module which contains directives such as +``define``, +``docopt``, +``export``, or +``fetch``, and you wish to modify those, +then you can override these settings in ``autocmake.yml``. +Settings in ``autocmake.yml`` take precedence over +settings imported by a sourced module. + +As an example consider the Boost module which defines and uses +interpolation variables ``major``, ``minor``, and ``patch``, see +https://github.com/coderefinery/autocmake/blob/master/modules/boost/boost.cmake#L52-L54. + +The recommended way to customize these is in ``autocmake.yml``, e.g.: +https://github.com/coderefinery/autocmake/blob/master/test/boost_libs/cmake/autocmake.yml#L12-L17. Create own CMake modules ------------------------ -Of course you can also create own modules and source them in ``autocmake.cfg``. +Of course you can also create own modules and source them in ``autocmake.yml``. Contribute customizations to the "standard library" diff --git a/doc/developers/example.rst b/doc/developers/example.rst index 8898fe6..b07b66a 100644 --- a/doc/developers/example.rst +++ b/doc/developers/example.rst @@ -4,7 +4,7 @@ Example Hello World project =========================== This is a brief example for the busy and impatient programmer. For a longer -tour please see :ref:`autocmake_cfg`. +tour please see :ref:`autocmake_yml`. We start with a mixed Fortran-C project with the following sources::