105 lines
4.3 KiB
ReStructuredText
105 lines
4.3 KiB
ReStructuredText
|
|
|
|
FAQ for developers
|
|
==================
|
|
|
|
|
|
Autocmake does not do feature X - I really need feature X and a setup.py flag --X
|
|
---------------------------------------------------------------------------------
|
|
|
|
The Autocmake developers have to be very conservative and only a very limited
|
|
set of portable features of absolutely general interest become part of the
|
|
Autocmake core or an Autocmake module. Autocmake developers are also busy.
|
|
|
|
Our recommendation is to not wait for the feature to be implemented: Implement
|
|
it yourself. Here we show you how. Code your feature in a module (i.e.
|
|
``my_feature.cmake``) and place the module under ``cmake/custom/`` (the
|
|
directory name is just a suggestion, Autocmake does not enforce a directory
|
|
naming)::
|
|
|
|
cmake/custom/my_feature.cmake
|
|
|
|
And include this feature to the main ``CMakeLists.txt`` in ``autocmake.cfg``::
|
|
|
|
[my_feature]
|
|
source: custom/my_feature.cmake
|
|
|
|
Now your code is included in the main ``CMakeLists.txt``. Perhaps you also
|
|
want a ``setup.py`` flag to toggle the feature::
|
|
|
|
[my_feature]
|
|
source: custom/my_feature.cmake
|
|
docopt: --my-feature Enable my feature [default: False].
|
|
define: '-DENABLE_MY_FEATURE=%s' % arguments['--my-feature']
|
|
|
|
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
|
|
the standard set of modules or even a core feature.
|
|
|
|
|
|
In CMake I can do feature X - can I do that also with Autocmake?
|
|
----------------------------------------------------------------
|
|
|
|
Yes. Autocmake is really just a simplistic script which helps to organize
|
|
CMake code across projects. Everything that can be done in CMake can be
|
|
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.py`` directly and expect everything to just work
|
|
(TM).
|
|
|
|
|
|
The update.py script is overwriting my CMakeLists.txt and setup.py, isn't this bad?
|
|
-----------------------------------------------------------------------------------
|
|
|
|
No, it is not as bad as it first looks. It is a feature. Normally
|
|
``CMakeLists.txt`` and ``setup.py`` should not contain any explicit
|
|
customization and therefore should not contain anything that could not be
|
|
regenerated. In any case you should use version control so that you can inspect
|
|
and compare changes introduced to ``CMakeLists.txt`` and ``setup.py`` and
|
|
possibly revert them. See also the next remark.
|
|
|
|
|
|
But I need to manually edit and customize CMakeLists.txt and setup.py every time I run update.py!?
|
|
--------------------------------------------------------------------------------------------------
|
|
|
|
You typically never need to manually edit and customize ``CMakeLists.txt`` and
|
|
``setup.py`` directly. You can introduce customizations in ``autocmake.cfg``
|
|
which get assembled into the front-end scripts.
|
|
|
|
|
|
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
|
|
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::
|
|
|
|
[src]
|
|
source: https://github.com/scisoft/autocmake/raw/master/modules/src.cmake
|
|
|
|
If you really don't 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
|
|
|
|
|
|
How do I know whether I need to rerun update.py?
|
|
------------------------------------------------
|
|
|
|
You need to rerun the ``update.py`` script in the following situations:
|
|
|
|
- To fetch updates to CMake modules which you include from the web.
|
|
- To regenerate ``CMakeLists.txt`` and the ``setup.py`` script.
|
|
- Every time you change ``autocmake.cfg``.
|