FAQ for developers ================== 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``. 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. 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 and of general interest, you can suggest it to be part of the standard set of modules or even a core feature.