Skip to content

Commit

Permalink
update documentation after API changes
Browse files Browse the repository at this point in the history
  • Loading branch information
@bast
bast committed Jul 18, 2016
1 parent 6353a2e commit 0da60d4
Show file tree
Hide file tree
Showing 11 changed files with 240 additions and 186 deletions.
3 changes: 3 additions & 0 deletions doc/developers/bootstrap.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@ infrastructure files which will be needed to build the project::
$ mkdir cmake # does not have to be called "cmake" - take the name you prefer
$ cd cmake
$ wget https://github.com/coderefinery/autocmake/raw/master/update.py
$ virtualenv venv
$ source venv/bin/activate
$ pip install pyyaml
$ python update.py --self

On the MS Windows system, you can use the PowerShell wget-replacement::
Expand Down
204 changes: 90 additions & 114 deletions doc/developers/configuration.rst
View file
Original file line number Diff line number Diff line change
@@ -1,115 +1,101 @@

.. _autocmake_yml:

Configuring autocmake.cfg
Configuring autocmake.yml
=========================

The script ``autocmake.cfg`` is the high level place where you configure
The script ``autocmake.yml`` 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/master/modules/fc.cmake

[cc]
source: https://github.com/coderefinery/autocmake/raw/master/modules/cc.cmake

[cxx]
source: https://github.com/coderefinery/autocmake/raw/master/modules/cxx.cmake

[flags]
source: https://github.com/coderefinery/autocmake/raw/master/compilers/GNU.CXX.cmake
https://github.com/coderefinery/autocmake/raw/master/compilers/Intel.CXX.cmake

[rpath]
source: custom/rpath.cmake

[definitions]
source: https://github.com/coderefinery/autocmake/raw/master/modules/definitions.cmake

[coverage]
source: https://github.com/coderefinery/autocmake/raw/master/modules/code_coverage.cmake

[safeguards]
source: https://github.com/coderefinery/autocmake/raw/master/modules/safeguards.cmake

[default_build_paths]
source: https://github.com/coderefinery/autocmake/raw/master/modules/default_build_paths.cmake

[src]
source: https://github.com/coderefinery/autocmake/raw/master/modules/src.cmake

[googletest]
source: https://github.com/coderefinery/autocmake/raw/master/modules/googletest.cmake
min_cmake_version: 2.8

[custom]
source: custom/api.cmake
custom/test.cmake
url_root: https://github.com/coderefinery/autocmake/raw/master/

modules:
- compilers:
- source:
- '%(url_root)modules/fc.cmake'
- '%(url_root)modules/cc.cmake'
- '%(url_root)modules/cxx.cmake'
- flags:
- source:
- '%(url_root)compilers/GNU.CXX.cmake'
- '%(url_root)compilers/Intel.CXX.cmake'
- 'compilers/Clang.CXX.cmake'
- plugins:
- source:
- '%(url_root)modules/ccache.cmake'
- 'custom/rpath.cmake'
- '%(url_root)modules/definitions.cmake'
- '%(url_root)modules/code_coverage.cmake'
- '%(url_root)modules/safeguards.cmake'
- '%(url_root)modules/default_build_paths.cmake'
- '%(url_root)modules/src.cmake'
- '%(url_root)modules/googletest.cmake'
- '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/master/modules/fc.cmake
First 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).

[two]
source: https://github.com/coderefinery/autocmake/raw/master/modules/cc.cmake
We also have to define ``min_cmake_version``.

[whatever]
source: https://github.com/coderefinery/autocmake/raw/master/modules/cxx.cmake
The definition ``url_root`` is an interpolation (see :ref:`interpolation`) and
we use it to avoid retyping the same line over and over and to be able to
change it in one place. The explicit name "url_root" has no special meaning to
Autocmake and we could have chosen a different name.

But it would not make much sense. It is better to choose names that are
meaningful to you.
The section ``modules`` is a list of CMake plugins. The names of the list
elements (here "compilers", "flags", and "plugins") does not matter to
Autocmake. We could have called them "one", "two", and "whatever", but it would
not make much sense. It is better to choose names that are meaningful to you
and readers of your code.

The order of the sections does matter and the sections will be processed in the
exact order as you specify them in ``autocmake.cfg``.
The order of the elements under ``modules`` does matter and the list will be
processed in the exact order as you specify them in ``autocmake.yml``.


Minimal example
---------------

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

[project]
name: minime
min_cmake_version: 2.8

If you don't have the ``update.py`` script yet, you need to fetch it from the web::

$ wget https://github.com/coderefinery/autocmake/raw/master/update.py

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 autocmake/configure.py
- fetching autocmake/__init__.py
- fetching autocmake/external/docopt.py
- fetching autocmake/external/__init__.py
- fetching autocmake/generate.py
- fetching autocmake/extract.py
- fetching autocmake/interpolate.py
- fetching autocmake/parse_rst.py
- fetching autocmake/parse_yaml.py
- fetching update.py

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

$ python update ..
$ python update.py ..

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

Expand Down Expand Up @@ -147,38 +133,38 @@ the following default options::
--show Show CMake command and exit.
--cmake-executable=<CMAKE_EXECUTABLE> Set the CMake executable [default: cmake].
--cmake-options=<STRING> Define options to CMake [default: ''].
--prefix=<PATH> Set the install path for make install.
<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.
``CMakeLists.txt`` by extending ``autocmake.yml`` 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``
The preferred way to extend ``CMakeLists.txt`` is by editing ``autocmake.yml``
and using the ``source`` option::

[fc]
source: https://github.com/coderefinery/autocmake/raw/master/modules/fc.cmake
- compilers:
- source:
- '%(url_root)modules/fc.cmake'
- '%(url_root)modules/cc.cmake'
- '%(url_root)modules/cxx.cmake'

This will download ``fc.cmake`` and include it in ``CMakeLists.txt``.
This will download ``fc.cmake``, ``cc.cmake``, and ``cxx.cmake``, and include
them in ``CMakeLists.txt``, in this order.

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/master/compilers/GNU.CXX.cmake
https://github.com/coderefinery/autocmake/raw/master/compilers/Intel.CXX.cmake
- source:
- 'custom/rpath.cmake'

The modules will be included in the same order as they appear in ``autocmake.cfg``.
It is also OK to include several modules at once as we have seen above. The
modules will be included in the same order as they appear in ``autocmake.yml``.


Fetching files without including them in CMakeLists.txt
Expand All @@ -187,9 +173,9 @@ 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/master/modules/git_info/git_info.cmake#L10-L11).
https://github.com/coderefinery/autocmake/blob/master/modules/git_info/git_info.cmake#L10-L13).

If ``fetch`` is invoked in ``autocmake.cfg``, then the fetched file is placed
If ``fetch`` is invoked in ``autocmake.yml``, 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.
Expand All @@ -199,11 +185,11 @@ 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
option. As an example, the following ``autocmake.yml`` snippet will add a
``--something`` flag::

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


Setting CMake options
Expand All @@ -213,9 +199,9 @@ 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'])
- my_section:
- docopt: "--something Enable something [default: False]."
- define: "'-DENABLE_SOMETHING={0}'.format(arguments['--enable-something'])"


Setting environment variables
Expand All @@ -224,33 +210,23 @@ 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']
docopt:
- "--cc=<CC> C compiler [default: gcc]."
- "--extra-cc-flags=<EXTRA_CFLAGS> Extra C compiler flags [default: '']."
export: "'CC={0}'.format(arguments['--cc'])"
define: "'-DEXTRA_CFLAGS=\"{0}\"'.format(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 avoid a boring re-typing of boilerplate ``autocmake.yml`` 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
The lines following ``# autocmake.yml configuration::`` are
understood by the ``update.py`` script to infer ``autocmake.yml`` code from the
documentation. As an example consider
https://github.com/coderefinery/autocmake/blob/master/modules/cc.cmake#L20-L25.
https://github.com/coderefinery/autocmake/blob/master/modules/cc.cmake#L20-L26.
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/master/modules/boost/boost.cmake#L33-L36.
These can be modified within ``autocmake.cfg`` with a dictionary, e.g.:
https://github.com/coderefinery/autocmake/blob/master/test/boost_libs/cmake/autocmake.cfg#L9
4 changes: 2 additions & 2 deletions doc/developers/customizing-modules.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,8 @@ Settings in ``autocmake.yml`` take precedence over
settings imported by a sourced module.

As an example consider the Boost module which defines and uses
interpolation variables ``major``, ``minor``, and ``patch``, see
https://github.com/coderefinery/autocmake/blob/master/modules/boost/boost.cmake#L52-L54.
interpolation variables ``major``, ``minor``, ``patch``, and ``components``, see
https://github.com/coderefinery/autocmake/blob/master/modules/boost/boost.cmake#L52-L55.

The recommended way to customize these is in ``autocmake.yml``, e.g.:
https://github.com/coderefinery/autocmake/blob/master/test/boost_libs/cmake/autocmake.yml#L12-L17.
Expand Down

0 comments on commit 0da60d4

Please sign in to comment.