FAQ for developers¶

Autocmake does not do feature X - I really need feature X and a setup 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 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'])

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.

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'])

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”:

[project]
name: myproject
min_cmake_version: 2.8
setup_script: configure

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 directly and expect everything to just work (TM).

The update.py script is overwriting my CMakeLists.txt and setup, isn’t this bad?¶

No, it is not as bad as it first looks. It is a feature. Normally CMakeLists.txt and setup 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 and possibly revert them. See also the next remark.

But I need to manually edit and customize CMakeLists.txt and setup every time I run update.py!?¶

You typically never need to manually edit and customize CMakeLists.txt and setup 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/coderefinery/autocmake/raw/stable-0.x/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 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). This file should implement a function with the following signature:

def postprocess_args(sys_argv, arguments):
    # sys_argv is the sys.argv from the setup script
    # arguments is the dictionary of arguments returned by docopt

    # do something here ...

    return arguments

In this function you can do any validation and post-processing you like. This function is run after the flags are parsed and before the CMake command is run.