AnotherFoxGuy/autocmake
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update documentation after API changes

Browse Source
This commit is contained in:
Radovan Bast
2016-07-18 12:17:15 +02:00
parent 6353a2e440
commit 0da60d43eb
11 changed files with 239 additions and 185 deletions
Download Patch File Download Diff File Expand all files Collapse all files

202
doc/developers/configuration.rst
View File

@ -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
url_root: https://github.com/coderefinery/autocmake/raw/master/
[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
[custom]
source: custom/api.cmake
custom/test.cmake
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]``::
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).
[project]
name: numgrid
min_cmake_version: 2.8
We also have to define ``min_cmake_version``.
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 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.
The names of the other sections do not matter to Autocmake. You could name them like this::
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.
[project]
name: numgrid
min_cmake_version: 2.8
[one]
source: https://github.com/coderefinery/autocmake/raw/master/modules/fc.cmake
[two]
source: https://github.com/coderefinery/autocmake/raw/master/modules/cc.cmake
[whatever]
source: https://github.com/coderefinery/autocmake/raw/master/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``.
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
@ -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
- 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
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
@ -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.
@ -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
@ -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
@ -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