update documentation after API changes
This commit is contained in:
@ -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
|
||||
|
Reference in New Issue
Block a user