update documentation after API changes

This commit is contained in:
Radovan Bast
2016-07-18 12:17:15 +02:00
parent 6353a2e440
commit 0da60d43eb
11 changed files with 239 additions and 185 deletions

View File

@ -4,6 +4,18 @@ FAQ for developers
==================
Which files do I need to edit?
------------------------------
Let us start with files which you normally never edit: ``CMakeLists.txt`` and
``setup`` - these are generated based on ``autocmake.yml``. Have a look in
``autocmake.yml`` and you will see all CMake files which are assembled into
``CMakeLists.txt``. You can edit those files. If you change the order of files
listed in ``autocmake.yml`` or if you add or remove CMake modules, then you
need to rerun the ``update.py`` script to refresh ``CMakeLists.txt`` and
``setup``.
Autocmake does not do feature X - I really need feature X and a setup flag --X
------------------------------------------------------------------------------
@ -19,18 +31,22 @@ naming)::
cmake/custom/my_feature.cmake
And include this feature to the main ``CMakeLists.txt`` in ``autocmake.cfg``::
And include this feature to the main ``CMakeLists.txt`` in ``autocmake.yml``
under the ``modules`` section::
[my_feature]
source: custom/my_feature.cmake
modules:
- my_feature:
- source:
- custom/my_feature.cmake
Now your code is included in the main ``CMakeLists.txt``. Perhaps you also
want a setup script flag to toggle the feature::
[my_feature]
source: custom/my_feature.cmake
docopt: --my-feature Enable my feature [default: False].
define: '-DENABLE_MY_FEATURE={0}'.format(arguments['--my-feature'])
- my_feature:
- docopt: "--enable-my-feature Enable my feature [default: False]."
- define: "'-DENABLE_MY_FEATURE={0}'.format(arguments['--enable-my-feature'])"
- source:
- custom/my_feature.cmake
Implement your ideas, test them, and share them. If your module is portable,
good code quality, and of general interest, you can suggest it to be part of
@ -43,17 +59,16 @@ How can I get a setup flag --X that toggles a CMake variable?
The following will add a ``--something`` flag which toggles the CMake variable
``ENABLE_SOMETHING``::
[my_section]
docopt: --something Enable something [default: False].
define: '-DENABLE_SOMETHING={0}'.format(arguments['--something'])
- my_section:
- docopt: "--something Enable something [default: False]."
- define: "'-DENABLE_SOMETHING={0}'.format(arguments['--enable-something'])"
Can I change the name of the setup script?
------------------------------------------
Yes you can do that in ``autocmake.cfg``. Here we for instance change the name to "configure"::
Yes you can do that in ``autocmake.yml``. Here we for instance change the name to "configure"::
[project]
name: myproject
min_cmake_version: 2.8
setup_script: configure
@ -70,12 +85,13 @@ realized in Autocmake.
Should I include and track also files generated by Autocmake in my repository?
------------------------------------------------------------------------------
Yes, you probably want to do that. Autocmake generates a number of files which
in principle could be generated at configure- or build-time. However, you
probably do not want the users of your code to run any Autocmake scripts like
``update.py`` to generate the files they need to build the project. The users
of your code will run ``setup`` directly and expect everything to just work
(TM).
Yes, you probably want to do that. Autocmake downloads and generates a number
of files which in principle could be generated at configure- or build-time.
However, you probably do not want the users of your code to run any Autocmake
scripts like ``update.py`` to generate the files they need to build the
project. The users of your code will run ``setup`` directly and typically expect
everything to just work (TM). Note also that the users of your code will
not need to install the pyyaml package.
The update.py script is overwriting my CMakeLists.txt and setup, isn't this bad?
@ -93,7 +109,7 @@ But I need to manually edit and customize CMakeLists.txt and setup every time I
-----------------------------------------------------------------------------------------------
You typically never need to manually edit and customize ``CMakeLists.txt`` and
``setup`` directly. You can introduce customizations in ``autocmake.cfg``
``setup`` directly. You can introduce customizations in ``autocmake.yml``
which get assembled into the front-end scripts.
@ -101,19 +117,21 @@ Where is a good place to list my sources and targets?
-----------------------------------------------------
As mentioned above ``CMakeLists.txt`` is not a good place because this file is
generated from ``autocmake.cfg`` and your modifications would become
generated from ``autocmake.yml`` and your modifications would become
overwritten at some point. A good standard is to organize your sources under
``src/`` and to list your sources and targets in ``src/CMakeLists.txt``. You
can include the latter in ``autocmake.cfg`` using::
can include the latter in ``autocmake.yml`` using::
[src]
source: https://github.com/coderefinery/autocmake/raw/master/modules/src.cmake
- my_sources:
- source:
- https://github.com/coderefinery/autocmake/raw/master/modules/src.cmake
If you really don't like to do it this way, you can describe your sources and
If you really do not like to do it this way, you can describe your sources and
targets in a custom module in a local file and include it like this::
[my_sources]
source: custom/my_sources.cmake
- my_sources:
- source:
- custom/my_sources.cmake
How can I do some more sophisticated validation of setup flags?
@ -121,7 +139,7 @@ How can I do some more sophisticated validation of setup flags?
Sometimes you need to do more sophisticated validation and post-processing
of setup flags. This can be done by placing a module called ``extensions.py``
under ``cmake/`` (or wherever you have ``autocmake.cfg``).
under ``cmake/`` (or wherever you have ``autocmake.yml``).
This file should implement a function with the following signature:
.. code-block:: python