Configuring autocmake.cfg¶

The script autocmake.cfg is the high level place where you configure your project. Here is an example. We will discuss it in detail further below:

[project]
name: numgrid
min_cmake_version: 2.8

[fc]
source: https://github.com/coderefinery/autocmake/raw/stable-0.x/modules/fc.cmake

[cc]
source: https://github.com/coderefinery/autocmake/raw/stable-0.x/modules/cc.cmake

[cxx]
source: https://github.com/coderefinery/autocmake/raw/stable-0.x/modules/cxx.cmake

[flags]
source: https://github.com/coderefinery/autocmake/raw/stable-0.x/compilers/GNU.CXX.cmake
        https://github.com/coderefinery/autocmake/raw/stable-0.x/compilers/Intel.CXX.cmake

[rpath]
source: custom/rpath.cmake

[definitions]
source: https://github.com/coderefinery/autocmake/raw/stable-0.x/modules/definitions.cmake

[coverage]
source: https://github.com/coderefinery/autocmake/raw/stable-0.x/modules/code_coverage.cmake

[safeguards]
source: https://github.com/coderefinery/autocmake/raw/stable-0.x/modules/safeguards.cmake

[default_build_paths]
source: https://github.com/coderefinery/autocmake/raw/stable-0.x/modules/default_build_paths.cmake

[src]
source: https://github.com/coderefinery/autocmake/raw/stable-0.x/modules/src.cmake

[googletest]
source: https://github.com/coderefinery/autocmake/raw/stable-0.x/modules/googletest.cmake

[custom]
source: custom/api.cmake
        custom/test.cmake

Name and order of sections¶

We see that the configuration file has sections. The only section where the name matters is [project]:

[project]
name: numgrid
min_cmake_version: 2.8

This is where we define the project name (here “numgrid”). This section has to be there and it has to be called “project” (but it does not have to be on top).

The names of the other sections do not matter to Autocmake. You could name them like this:

[project]
name: numgrid
min_cmake_version: 2.8

[one]
source: https://github.com/coderefinery/autocmake/raw/stable-0.x/modules/fc.cmake

[two]
source: https://github.com/coderefinery/autocmake/raw/stable-0.x/modules/cc.cmake

[whatever]
source: https://github.com/coderefinery/autocmake/raw/stable-0.x/modules/cxx.cmake

But it would not make much sense. It is better to choose names that are meaningful to you.

The order of the sections does matter and the sections will be processed in the exact order as you specify them in autocmake.cfg.

Minimal example¶

As a minimal example we take an autocmake.cfg which only contains:

[project]
name: minime
min_cmake_version: 2.8

First we make sure that the update.py script is up-to-date and that it has access to all libraries it needs:

$ python update.py --self

- creating .gitignore
- fetching lib/config.py
- fetching lib/docopt/docopt.py
- fetching update.py

Good. Now we can generate CMakeLists.txt and the setup script:

$ python update ..

- parsing autocmake.cfg
- generating CMakeLists.txt
- generating setup script

Excellent. Here is the generated CMakeLists.txt:

# set minimum cmake version
cmake_minimum_required(VERSION 2.8 FATAL_ERROR)

# project name
project(minime)

# do not rebuild if rules (compiler flags) change
set(CMAKE_SKIP_RULE_DEPENDENCY TRUE)

# if CMAKE_BUILD_TYPE undefined, we set it to Debug
if(NOT CMAKE_BUILD_TYPE)
    set(CMAKE_BUILD_TYPE "Debug")
endif()

set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${PROJECT_SOURCE_DIR}/cmake/downloaded)

This is the very bare minimum. Every Autocmake project will have at least these settings.

And we also got a setup script (front-end to CMakeLists.txt) with the following default options:

Usage:
  ./setup [options] [<builddir>]
  ./setup (-h | --help)

Options:
  --type=<TYPE>                          Set the CMake build type (debug, release, or relwithdeb) [default: release].
  --generator=<STRING>                   Set the CMake build system generator [default: Unix Makefiles].
  --show                                 Show CMake command and exit.
  --cmake-executable=<CMAKE_EXECUTABLE>  Set the CMake executable [default: cmake].
  --cmake-options=<STRING>               Define options to CMake [default: ''].
  <builddir>                             Build directory.
  -h --help                              Show this screen.

That’s not too bad although currently we cannot do much with this since there are no sources listed, no targets, hence nothing to build. We need to flesh out CMakeLists.txt by extending autocmake.cfg and this is what we will do in the next section.

Assembling CMake plugins¶

The preferred way to extend CMakeLists.txt is by editing autocmake.cfg and using the source option:

[fc]
source: https://github.com/coderefinery/autocmake/raw/stable-0.x/modules/fc.cmake

This will download fc.cmake and include it in CMakeLists.txt.

You can also include local CMake modules, e.g.:

[rpath]
source: custom/rpath.cmake

It is also OK to include several modules at once:

[flags]
source: https://github.com/coderefinery/autocmake/raw/stable-0.x/compilers/GNU.CXX.cmake
        https://github.com/coderefinery/autocmake/raw/stable-0.x/compilers/Intel.CXX.cmake

The modules will be included in the same order as they appear in autocmake.cfg.

Fetching files without including them in CMakeLists.txt¶

Sometimes you want to fetch a file without including it in CMakeLists.txt. This can be done with the fetch option. This is for instance done by the git_info.cmake module (see https://github.com/coderefinery/autocmake/blob/stable-0.x/modules/git_info/git_info.cmake#L10-L11).

If fetch is invoked in autocmake.cfg, then the fetched file is placed under downloaded/. If fetch is invoked from within a CMake module documentation (see below), then the fetched file is placed into the same directory as the CMake module file which fetches it.

Generating setup options¶

Options for the setup script can be generated with the docopt option. As an example, the following autocmake.cfg snippet will add a --something flag:

[my_section]
docopt: --something Enable something [default: False].

Setting CMake options¶

Configure-time CMake options can be generated with the define option. Consider the following example which toggles the CMake variable ENABLE_SOMETHING:

[my_section]
docopt: --something Enable something [default: False].
define: '-DENABLE_SOMETHING={0}'.format(arguments['--something'])

Setting environment variables¶

You can export environment variables at configure-time using the export option. Consider the following example:

[cc]
docopt: --cc=<CC> C compiler [default: gcc].
        --extra-cc-flags=<EXTRA_CFLAGS> Extra C compiler flags [default: ''].
export: 'CC=%s' % arguments['--cc']
define: '-DEXTRA_CFLAGS="%s"' % arguments['--extra-cc-flags']

Auto-generating configurations from the documentation¶

To avoid a boring re-typing of boilerplate autocmake.cfg code it is possible to auto-generate configurations from the documentation. This is the case for many core modules which come with own options once you have sourced them.

The lines following # autocmake.cfg configuration:: are understood by the update.py script to infer autocmake.cfg code from the documentation. As an example consider https://github.com/coderefinery/autocmake/blob/stable-0.x/modules/cc.cmake#L20-L25. Here, update.py will infer the configurations for docopt, export, and define.

Overriding documented configurations¶

Configurable documented defaults can be achieved using interpolations. See for instance https://github.com/coderefinery/autocmake/blob/stable-0.x/modules/boost/boost.cmake#L33-L36. These can be modified within autocmake.cfg with a dictionary, e.g.: https://github.com/coderefinery/autocmake/blob/stable-0.x/test/boost_libs/cmake/autocmake.cfg#L9