update documentation after API changes
This commit is contained in:
Radovan Bast
parent
6353a2e440
commit
0da60d43eb
@ -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::
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
|
||||
|
||||
Example Hello World project
|
||||
Example hello world project
|
||||
===========================
|
||||
|
||||
This is a brief example for the busy and impatient programmer. For a longer
|
||||
@ -23,40 +23,49 @@ there. This is not necessary for Autocmake but it is a generally good practice::
|
||||
|
||||
Now we create ``cmake/`` and fetch ``update.py``::
|
||||
|
||||
$ mkdir cmake
|
||||
$ cd cmake/
|
||||
$ wget https://raw.githubusercontent.com/coderefinery/autocmake/master/update.py
|
||||
$ 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
|
||||
$ python update.py --self
|
||||
|
||||
Now from top-level our file tree looks like this::
|
||||
|
||||
.
|
||||
|-- cmake
|
||||
| |-- autocmake.cfg
|
||||
| |-- lib
|
||||
| | |-- config.py
|
||||
| | `-- docopt
|
||||
| | `-- docopt.py
|
||||
| |-- autocmake
|
||||
| | |-- __init__.py
|
||||
| | |-- configure.py
|
||||
| | |-- external
|
||||
| | | |-- __init__.py
|
||||
| | | `-- docopt.py
|
||||
| | |-- extract.py
|
||||
| | |-- generate.py
|
||||
| | |-- interpolate.py
|
||||
| | |-- parse_rst.py
|
||||
| | `-- parse_yaml.py
|
||||
| |-- autocmake.yml
|
||||
| `-- update.py
|
||||
`-- src
|
||||
|-- feature1.F90
|
||||
|-- feature2.c
|
||||
`-- main.F90
|
||||
|
||||
Now we edit ``cmake/autocmake.cfg`` to look like this::
|
||||
Now we edit ``cmake/autocmake.yml`` to look like this::
|
||||
|
||||
[project]
|
||||
name: hello
|
||||
|
||||
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
|
||||
|
||||
[src]
|
||||
source: https://github.com/coderefinery/autocmake/raw/master/modules/src.cmake
|
||||
modules:
|
||||
- compilers:
|
||||
- source:
|
||||
- '%(url_root)modules/fc.cmake'
|
||||
- '%(url_root)modules/cc.cmake'
|
||||
- src_support:
|
||||
- source:
|
||||
- '%(url_root)modules/src.cmake'
|
||||
|
||||
What we have specified here is the project name and that we wish Fortran and C
|
||||
support. The ``src.cmake`` module tells CMake to include a ``src/CMakeLists.txt``.
|
||||
@ -76,20 +85,32 @@ Now we have everything to generate ``CMakeLists.txt`` and a setup script::
|
||||
$ cd cmake
|
||||
$ python update ..
|
||||
|
||||
- parsing autocmake.yml
|
||||
- assembling modules: [##############################] (3/3)
|
||||
- generating CMakeLists.txt
|
||||
- generating setup script
|
||||
|
||||
And this is what we got::
|
||||
|
||||
.
|
||||
|-- CMakeLists.txt
|
||||
|-- cmake
|
||||
| |-- autocmake.cfg
|
||||
| |-- autocmake
|
||||
| | |-- __init__.py
|
||||
| | |-- configure.py
|
||||
| | |-- external
|
||||
| | | |-- __init__.py
|
||||
| | | `-- docopt.py
|
||||
| | |-- extract.py
|
||||
| | |-- generate.py
|
||||
| | |-- interpolate.py
|
||||
| | |-- parse_rst.py
|
||||
| | `-- parse_yaml.py
|
||||
| |-- autocmake.yml
|
||||
| |-- downloaded
|
||||
| | |-- autocmake_cc.cmake
|
||||
| | |-- autocmake_fc.cmake
|
||||
| | `-- autocmake_src.cmake
|
||||
| |-- lib
|
||||
| | |-- config.py
|
||||
| | `-- docopt
|
||||
| | `-- docopt.py
|
||||
| `-- update.py
|
||||
|-- setup
|
||||
`-- src
|
||||
@ -100,12 +121,12 @@ And this is what we got::
|
||||
|
||||
Now we are ready to build::
|
||||
|
||||
$ python setup --fc=gfortran --cc=gcc
|
||||
$ ./setup --fc=gfortran --cc=gcc
|
||||
|
||||
FC=gfortran CC=gcc cmake -DEXTRA_FCFLAGS="''" -DENABLE_FC_SUPPORT="ON" -DEXTRA_CFLAGS="''" -DCMAKE_BUILD_TYPE=release -G "Unix Makefiles" None /home/user/example
|
||||
FC=gfortran CC=gcc cmake -DEXTRA_FCFLAGS="''" -DEXTRA_CFLAGS="''" -DCMAKE_BUILD_TYPE=release -G "Unix Makefiles" /home/user/hello
|
||||
|
||||
-- The C compiler identification is GNU 4.9.2
|
||||
-- The CXX compiler identification is GNU 4.9.2
|
||||
-- The C compiler identification is GNU 6.1.1
|
||||
-- The CXX compiler identification is GNU 6.1.1
|
||||
-- Check for working C compiler: /usr/bin/gcc
|
||||
-- Check for working C compiler: /usr/bin/gcc -- works
|
||||
-- Detecting C compiler ABI info
|
||||
@ -118,7 +139,7 @@ Now we are ready to build::
|
||||
-- Detecting CXX compiler ABI info - done
|
||||
-- Detecting CXX compile features
|
||||
-- Detecting CXX compile features - done
|
||||
-- The Fortran compiler identification is GNU 4.9.2
|
||||
-- The Fortran compiler identification is GNU 6.1.1
|
||||
-- Check for working Fortran compiler: /usr/bin/gfortran
|
||||
-- Check for working Fortran compiler: /usr/bin/gfortran -- works
|
||||
-- Detecting Fortran compiler ABI info
|
||||
@ -127,14 +148,14 @@ Now we are ready to build::
|
||||
-- Checking whether /usr/bin/gfortran supports Fortran 90 -- yes
|
||||
-- Configuring done
|
||||
-- Generating done
|
||||
-- Build files have been written to: /home/user/example/build
|
||||
-- Build files have been written to: /home/user/hello/build
|
||||
|
||||
configure step is done
|
||||
now you need to compile the sources:
|
||||
$ cd build
|
||||
$ make
|
||||
|
||||
$ cd build/
|
||||
$ cd build
|
||||
$ make
|
||||
|
||||
Scanning dependencies of target hello.x
|
||||
|
||||
@ -4,6 +4,18 @@ FAQ for developers
|
||||
==================
|
||||
|
||||
|
||||
Which files do I need to edit?
|
||||
------------------------------
|
||||
|
||||
Let us start with files which you normally never edit: ``CMakeLists.txt`` and
|
||||
``setup`` - these are generated based on ``autocmake.yml``. Have a look in
|
||||
``autocmake.yml`` and you will see all CMake files which are assembled into
|
||||
``CMakeLists.txt``. You can edit those files. If you change the order of files
|
||||
listed in ``autocmake.yml`` or if you add or remove CMake modules, then you
|
||||
need to rerun the ``update.py`` script to refresh ``CMakeLists.txt`` and
|
||||
``setup``.
|
||||
|
||||
|
||||
Autocmake does not do feature X - I really need feature X and a setup flag --X
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
@ -19,18 +31,22 @@ naming)::
|
||||
|
||||
cmake/custom/my_feature.cmake
|
||||
|
||||
And include this feature to the main ``CMakeLists.txt`` in ``autocmake.cfg``::
|
||||
And include this feature to the main ``CMakeLists.txt`` in ``autocmake.yml``
|
||||
under the ``modules`` section::
|
||||
|
||||
[my_feature]
|
||||
source: custom/my_feature.cmake
|
||||
modules:
|
||||
- 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'])
|
||||
- my_feature:
|
||||
- docopt: "--enable-my-feature Enable my feature [default: False]."
|
||||
- define: "'-DENABLE_MY_FEATURE={0}'.format(arguments['--enable-my-feature'])"
|
||||
- source:
|
||||
- custom/my_feature.cmake
|
||||
|
||||
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
|
||||
@ -43,17 +59,16 @@ 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'])
|
||||
- my_section:
|
||||
- docopt: "--something Enable something [default: False]."
|
||||
- define: "'-DENABLE_SOMETHING={0}'.format(arguments['--enable-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"::
|
||||
Yes you can do that in ``autocmake.yml``. Here we for instance change the name to "configure"::
|
||||
|
||||
[project]
|
||||
name: myproject
|
||||
min_cmake_version: 2.8
|
||||
setup_script: configure
|
||||
@ -70,12 +85,13 @@ 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).
|
||||
Yes, you probably want to do that. Autocmake downloads and 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 typically expect
|
||||
everything to just work (TM). Note also that the users of your code will
|
||||
not need to install the pyyaml package.
|
||||
|
||||
|
||||
The update.py script is overwriting my CMakeLists.txt and setup, isn't this bad?
|
||||
@ -93,7 +109,7 @@ But I need to manually edit and customize CMakeLists.txt and setup every time I
|
||||
-----------------------------------------------------------------------------------------------
|
||||
|
||||
You typically never need to manually edit and customize ``CMakeLists.txt`` and
|
||||
``setup`` directly. You can introduce customizations in ``autocmake.cfg``
|
||||
``setup`` directly. You can introduce customizations in ``autocmake.yml``
|
||||
which get assembled into the front-end scripts.
|
||||
|
||||
|
||||
@ -101,19 +117,21 @@ 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
|
||||
generated from ``autocmake.yml`` 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::
|
||||
can include the latter in ``autocmake.yml`` using::
|
||||
|
||||
[src]
|
||||
source: https://github.com/coderefinery/autocmake/raw/master/modules/src.cmake
|
||||
- my_sources:
|
||||
- source:
|
||||
- https://github.com/coderefinery/autocmake/raw/master/modules/src.cmake
|
||||
|
||||
If you really don't like to do it this way, you can describe your sources and
|
||||
If you really do not 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
|
||||
- my_sources:
|
||||
- source:
|
||||
- custom/my_sources.cmake
|
||||
|
||||
|
||||
How can I do some more sophisticated validation of setup flags?
|
||||
@ -121,7 +139,7 @@ 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``).
|
||||
under ``cmake/`` (or wherever you have ``autocmake.yml``).
|
||||
This file should implement a function with the following signature:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
34
doc/developers/interpolation.rst
Normal file
34
doc/developers/interpolation.rst
Normal file
@ -0,0 +1,34 @@
|
||||
|
||||
.. _interpolation:
|
||||
|
||||
Interpolation
|
||||
=============
|
||||
|
||||
In a custom extension to the YAML specification you can define and reuse
|
||||
variables like this (observe how we interpolate ``url_root``, ``major``,
|
||||
``minor``, ``patch``, and ``components`` in this example)::
|
||||
|
||||
url_root: https://github.com/coderefinery/autocmake/raw/master/
|
||||
major: 1
|
||||
minor: 48
|
||||
patch: 0
|
||||
components: ""
|
||||
fetch:
|
||||
- "%(url_root)modules/boost/boost_unpack.cmake"
|
||||
- "%(url_root)modules/boost/boost_userconfig.cmake"
|
||||
- "%(url_root)modules/boost/boost_configure.cmake"
|
||||
- "%(url_root)modules/boost/boost_build.cmake"
|
||||
- "%(url_root)modules/boost/boost_install.cmake"
|
||||
- "%(url_root)modules/boost/boost_headers.cmake"
|
||||
- "%(url_root)modules/boost/boost_cleanup.cmake"
|
||||
- "http://sourceforge.net/projects/boost/files/boost/%(major).%(minor).%(patch)/boost_%(major)_%(minor)_%(patch).zip"
|
||||
docopt:
|
||||
- "--boost-headers=<BOOST_INCLUDEDIR> Include directories for Boost [default: '']."
|
||||
- "--boost-libraries=<BOOST_LIBRARYDIR> Library directories for Boost [default: '']."
|
||||
- "--build-boost=<FORCE_CUSTOM_BOOST> Deactivate Boost detection and build on-the-fly <ON/OFF> [default: OFF]."
|
||||
define:
|
||||
- "'-DBOOST_INCLUDEDIR=\"{0}\"'.format(arguments['--boost-headers'])"
|
||||
- "'-DBOOST_LIBRARYDIR=\"{0}\"'.format(arguments['--boost-libraries'])"
|
||||
- "'-DFORCE_CUSTOM_BOOST={0}'.format(arguments['--build-boost'])"
|
||||
- "'-DBOOST_MINIMUM_REQUIRED=\"%(major).%(minor).%(patch)\"'"
|
||||
- "'-DBOOST_COMPONENTS_REQUIRED=\"%(components)\"'"
|
||||
@ -20,11 +20,11 @@ Sometimes you may want to avoid using the latest version of a CMake module and
|
||||
rather fetch an older version, for example with the hash ``abcd123``. To
|
||||
achieve this, instead of::
|
||||
|
||||
[foo]
|
||||
source: https://github.com/coderefinery/autocmake/raw/master/modules/foo.cmake
|
||||
- my_feature:
|
||||
- source: https://github.com/coderefinery/autocmake/raw/master/modules/foo.cmake
|
||||
|
||||
pin the version to ``abcd123`` (you do not need to specify the full Git hash, a unique
|
||||
beginning will do)::
|
||||
|
||||
[foo]
|
||||
source: https://github.com/coderefinery/autocmake/raw/abcd123/modules/foo.cmake
|
||||
- my_feature:
|
||||
- source: https://github.com/coderefinery/autocmake/raw/abcd123/modules/foo.cmake
|
||||
|
||||
@ -38,7 +38,7 @@ file::
|
||||
Build/install/test targets
|
||||
|
||||
Our main motivation to create Autocmake as a CMake framework library and
|
||||
CMake module composer is to simplify CMake code transfer between codes. We got
|
||||
CMake module composer is to simplify CMake code transfer between programs. We got
|
||||
tired of manually diffing and copy-pasting boiler-plate CMake code and watching
|
||||
it diverge while maintaining the CMake infrastructure in a growing number of
|
||||
scientific projects which typically have very similar requirements:
|
||||
|
||||
@ -8,3 +8,6 @@ support Python 3 (we automatically test with 2.7 and 3.5).
|
||||
|
||||
The generated setup script runs with Python >= 2.6 (also tested with Python
|
||||
3.5).
|
||||
|
||||
To generate ``CMakeLists.txt`` and the ``setup`` script, Autocmake
|
||||
requires the pyyaml package.
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
|
||||
|
||||
Autocmake (this documentation is outdated, see stable-0.x branch)
|
||||
=================================================================
|
||||
Autocmake
|
||||
=========
|
||||
|
||||
|
||||
General
|
||||
@ -27,6 +27,7 @@ For developers who use Autocmake
|
||||
developers/example.rst
|
||||
developers/customizing-modules.rst
|
||||
developers/updating-modules.rst
|
||||
developers/interpolation.rst
|
||||
|
||||
|
||||
For users of projects which use Autocmake
|
||||
|
||||
@ -49,9 +49,7 @@ Like this::
|
||||
|
||||
$ python setup --cmake-options='"-DTHIS_OPTION=ON -DTHAT_OPTION=OFF"'
|
||||
|
||||
We use two sets of quotes because the shell swallows one set of them
|
||||
before passing the arguments to Python. Yeah that's not nice, but nothing
|
||||
we can do about it on the Python side.
|
||||
If you do not use two sets
|
||||
of quotes then the setup command may end up
|
||||
incorrectly saved in `build/setup_command`.
|
||||
We use two sets of quotes because the shell swallows one set of them before
|
||||
passing the arguments to Python. Yeah that's not nice, but nothing we can do
|
||||
about it on the Python side. If you do not use two sets of quotes then the
|
||||
setup command may end up incorrectly saved in `build/setup_command`.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user