diff --git a/doc/developers/bootstrap.rst b/doc/developers/bootstrap.rst index e8e2798..051535b 100644 --- a/doc/developers/bootstrap.rst +++ b/doc/developers/bootstrap.rst @@ -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:: diff --git a/doc/developers/configuration.rst b/doc/developers/configuration.rst index 5496923..084a6b8 100644 --- a/doc/developers/configuration.rst +++ b/doc/developers/configuration.rst @@ -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 @@ -147,38 +133,38 @@ the following default options:: --show Show CMake command and exit. --cmake-executable= Set the CMake executable [default: cmake]. --cmake-options= Define options to CMake [default: '']. + --prefix= Set the install path for make install. 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 @@ -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= C compiler [default: gcc]. - --extra-cc-flags= Extra C compiler flags [default: '']. - export: 'CC=%s' % arguments['--cc'] - define: '-DEXTRA_CFLAGS="%s"' % arguments['--extra-cc-flags'] + docopt: + - "--cc= C compiler [default: gcc]." + - "--extra-cc-flags= 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 diff --git a/doc/developers/customizing-modules.rst b/doc/developers/customizing-modules.rst index fd6a37b..5122396 100644 --- a/doc/developers/customizing-modules.rst +++ b/doc/developers/customizing-modules.rst @@ -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. diff --git a/doc/developers/example.rst b/doc/developers/example.rst index b07b66a..4d83150 100644 --- a/doc/developers/example.rst +++ b/doc/developers/example.rst @@ -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 + min_cmake_version: 2.8 - [cc] - source: https://github.com/coderefinery/autocmake/raw/master/modules/cc.cmake + url_root: https://github.com/coderefinery/autocmake/raw/master/ - [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 diff --git a/doc/developers/faq.rst b/doc/developers/faq.rst index 0524dce..0c8e4ef 100644 --- a/doc/developers/faq.rst +++ b/doc/developers/faq.rst @@ -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 diff --git a/doc/developers/interpolation.rst b/doc/developers/interpolation.rst new file mode 100644 index 0000000..1a2dff8 --- /dev/null +++ b/doc/developers/interpolation.rst @@ -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= Include directories for Boost [default: '']." + - "--boost-libraries= Library directories for Boost [default: '']." + - "--build-boost= Deactivate Boost detection and build on-the-fly [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)\"'" diff --git a/doc/developers/updating-modules.rst b/doc/developers/updating-modules.rst index 7fdd8be..834aeb7 100644 --- a/doc/developers/updating-modules.rst +++ b/doc/developers/updating-modules.rst @@ -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 diff --git a/doc/general/about.rst b/doc/general/about.rst index ea6cb11..7a75ac2 100644 --- a/doc/general/about.rst +++ b/doc/general/about.rst @@ -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: diff --git a/doc/general/requirements.rst b/doc/general/requirements.rst index 6d27d85..453c3a1 100644 --- a/doc/general/requirements.rst +++ b/doc/general/requirements.rst @@ -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. diff --git a/doc/index.rst b/doc/index.rst index 5356a95..e28c430 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -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 diff --git a/doc/users/faq.rst b/doc/users/faq.rst index d9e7ef2..68d0822 100644 --- a/doc/users/faq.rst +++ b/doc/users/faq.rst @@ -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`.