[Dune-devel] [Dune-Commit] dune-web r1460 - doc
Carsten Gräser
graeser at mi.fu-berlin.de
Wed Sep 16 11:57:56 CEST 2015
Hi Christoph,
thanks a lot for updating the install notes. This was
an (the last?) important missing piece for 2.4. Currently
the notes 'only' explain how to pass subcommand options
which may tempt users to rely on the compatibility mode
translating the old autotools options for cmake.
Shouldn't we teach them how to properly pass cmake
options, e.g., like this
CMAKE_FLAGS="
-DCMAKE_CXX_COMPILER='foo++'\
-DCMAKE_CXX_FLAGS='-O42 -fsupergenerate--very-fast -Wall'\
-DCMAKE_PREFIX_PATH='~/mythirdpartylibs'\
"
Nevertheless I encourage EVERYONE to carefully read the
updated instructions with the eyes of a cmake newbie
to find inconsistencies, missing things,...
Remember that a release can only be as good as its installation
notes. If we fail here, our users will never see all our shiny
new and polished features.
Best,
Carsten
Am 16.09.2015 um 05:49 schrieb gruenich at dune-project.org:
> Author: gruenich
> Date: 2015-09-16 05:49:12 +0200 (Wed, 16 Sep 2015)
> New Revision: 1460
>
> Added:
> doc/installation-notes-autotools.wml
> Modified:
> doc/installation-notes.wml
> Log:
> [install_notes] Update to CMake.
>
> Move old one to own file for people sticking with Autotools.
>
>
> Copied: doc/installation-notes-autotools.wml (from rev 1459, doc/installation-notes.wml)
> ===================================================================
> --- doc/installation-notes-autotools.wml (rev 0)
> +++ doc/installation-notes-autotools.wml 2015-09-16 03:49:12 UTC (rev 1460)
> @@ -0,0 +1,202 @@
> +# -*- html -*-
> +
> +#use wml::layout::default title="DUNE - Installation Notes for Autotools"
> +
> +<h1>Installation Notes</h1>
> +
> +These installation notes for Autotools are outdated. Beginning with DUNE 2.4
> +CMake is the official build-system. Use the <a href="installation-notes.html">
> +current instructions</a>.
> +
> +<h2>Dependencies</h2>
> +
> +<p>
> +In order to build DUNE you need at least the following software:
> +</p>
> +<ul>
> +<li>a standard compliant C++ compiler, tested are g++ (>= 4.4)
> +and Clang (>=3.4). Recent versions of ICC (>= 15) should work,
> +older versions like 14.0.3 needs patching of system headers
> +and is discouraged.
> +<a href="http://users.dune-project.org/projects/main-wiki/wiki/Compilers">(More)</a></li>
> +<li>pkg-config</li>
> +</ul>
> +<p>
> +The following software is recommend but optional:
> +</p>
> +<ul>
> +<li>MPI (either OpenMPI, lam, or mpich suffice)</li>
> +</ul>
> +<p>
> +When building the development version of DUNE you will also need
> +</p>
> +<ul>
> +<li>automake (>= 1.9)</li>
> +<li>autoconf (>= 2.62)</li>
> +<li>libtool (>= 2.2)</li>
> +</ul>
> +<p>
> +This will provide you with the core DUNE features.</p>
> +<p>
> +Some DUNE modules might support further software. Using this software
> +is optional. The dune-grid module for example supports different
> +external grid managers like Alberta or UG; these have to be downloaded
> +separately. For a list of supported contrib software packages and
> +their installation see the notes on
> +<a href="$(ROOT)/external_libraries/index.html">Installation External Libraries</a>.
> +</p>
> +
> +<h2>Installing the core DUNE modules</h2>
> +
> +<p>
> +Suppose you have downloaded all DUNE modules of interest to your
> +computer and extracted then in one common directory. See the <a
> +href="$(ROOT)/download.html">download</a> section
> +for a list of available modules.
> +</p>
> +<p>
> +To compile the modules DUNE has to check several components of
> +your system and whether prerequisites within the modules are met. For
> +the ease of users we have designed a custom build system on top of the
> +automake tools. Run
> +</p>
> +<pre>
> + ./dune-common/bin/dunecontrol all
> +</pre>
> +<p>
> +to commence those tests and build all modules you have
> +downloaded. Don't worry about messages telling you that libraries are
> +missing: they are only needed for grid-self-checks we need for
> +developing.
> +</p>
> +<p>
> +You can customize the build to your specific needs by using an options file
> +(see below)
> +</p>
> +<pre>
> + ./dune-common/bin/dunecontrol --opts=/path_to/file.opts
> +</pre>
> +<p>
> +If you did not tell dunecontrol to install with an options file you
> +need to run
> +</p>
> +<pre>
> + ./dune-common/bin/dunecontrol make install
> +</pre>
> +<p>
> +to install DUNE (you may need root-permissions for the install
> +part depending on the prefix set)
> +</p>
> +<p>
> +A more comprehensive introduction to the build system can be found in
> +the <a href="buildsystem/buildsystem.pdf">Dune Build System Howto</a>.
> +</p>
> +
> +<h3>Building a specific DUNE module (and its dependent modules)</h3>
> +
> +<p>You can instruct dunecontrol to build only a certain dune module,
> +using the <kbd>--only=module_name></kbd> switch.
> +Runnning dunecontrol script
> +<p>
> +<pre>
> +./dune-common/bin/dunecontrol --only=<module_name> all
> +</pre>
> +</p>
> +where <module_name> is the name of that particular module given in the
> +dune.module file, will build only the module <module_name>.
> +</p>
> +
> +<p>If you want to build a module and the modules it depends on, you
> +must run:</p>
> +<pre>
> +./dune-common/bin/dunecontrol --module=module_name all
> +</pre>
> +<p> Read <a href="http://dune-project.org/dunemodule.html">Maintaining new Dune modules and applications</a> section for more details.
> +</p>
> +
> +<h3>Passing options to the build process</h3>
> +
> +<p>
> +Using the dunecontrol script the following atomic commands can be
> +executed:
> +</p>
> +<ul>
> +<li>
> +autogen (runs autogen in each module, only needed when downloaded
> +via Git)
> +</li>
> +<li>
> +configure (runs the configure tests for each module
> +</li>
> +<li>
> +exec (executes a command in each module directory)
> +</li>
> +<li>
> +make (runs make for each module)
> +</li>
> +<li>
> +update (updates the Git version)
> +</li>
> +</ul>
> +<p>
> +The composite command all simply runs autogen, configure and make for
> +each module.
> +</p>
> +<p>
> +As it is often not convenient (and for the target all impossible) to
> +specify the options for each command as parameters after the call, one
> +can pass the options via file specified by the <kbd>--opts=<file></kbd>
> +option. For each atomic command one specify the options via a ine
> +</p>
> +<pre>
> +<COMMAND_UPPERCASE>_FLAGS=<flags> # e.g.: MAKE_FLAGS=install
> +</pre>
> +<p>
> +The available options for make are the natural ones. The
> +configure commands available can be found by issuing
> +</p>
> +<pre>
> +dunecontrol --only=dune-common configure --help
> +</pre>
> +<p>
> +and for autogen by
> +</p>
> +<pre>
> +dunecontrol --only=dune-common autogen --help
> +</pre>
> +<p>
> +(In the Git version this has to be called after running autogen.)
> +</p>
> +<p>
> +An example of an options file is
> +</p>
> +<pre>
> + \# use a special compiler (g++ version 3.4) and install to a custom
> + \# directory, default is /usr/local/bin
> + CONFIGURE_FLAGS="CXX=g++-3.4 --prefix='/tmp/HuHu'"
> + \# Set the default target of make to install. Now the call above will
> + \# not just build the DUNE modules but also install it
> + MAKE_FLAGS=install
> + \# The default versions of automake and autogen are not sufficient
> + \# therefore we need to specify what versions to use
> + AUTOGEN_FLAGS="--ac=2.59 --am=1.9"
> +</pre>
> +
> +<p>On some platforms special care might have to be taken to make
> + things compile, e.g. this is the case for IBM's Blue Gene System
> + P. If you want to run DUNE there please read the <a href="installation-notes-bluegenep.html">instructions</a> of
> + Markus and save yourself a lot of time.
> +</p>
> +
> +<h2>Creating your own DUNE project module</h2>
> +<p>
> +You can create your own dune project module by using the duneproject script available in dune-common/bin directory.
> +Running the script will create a directory with supporting files
> +(configure.ac, Makefile.am etc.) and a sample .cc file.
> +After creating the module you can build this as explained above under "Building a specific DUNE module".
> +</p>
> +<p>The <a
> +href="http://dune-project.org/doc/buildsystem/buildsystem.pdf">DUNE
> +Build System Howto</a> will also give you an excellent introduction to
> +the build system and how to create new modules/projects your own.
> +</p>
>
> Modified: doc/installation-notes.wml
> ===================================================================
> --- doc/installation-notes.wml 2015-09-12 22:17:57 UTC (rev 1459)
> +++ doc/installation-notes.wml 2015-09-16 03:49:12 UTC (rev 1460)
> @@ -4,6 +4,10 @@
>
> <h1>Installation Notes</h1>
>
> +These installation notes explain how to use CMake. If you stick with the legacy
> +Autotools build-system, use the <a href="installation-notes-autotools.html">
> +old instructions</a>.
> +
> <h2>Dependencies</h2>
>
> <p>
> @@ -15,6 +19,7 @@
> older versions like 14.0.3 needs patching of system headers
> and is discouraged.
> <a href="http://users.dune-project.org/projects/main-wiki/wiki/Compilers">(More)</a></li>
> +<li>CMake (>= 2.8.6)</li>
> <li>pkg-config</li>
> </ul>
> <p>
> @@ -24,14 +29,6 @@
> <li>MPI (either OpenMPI, lam, or mpich suffice)</li>
> </ul>
> <p>
> -When building the development version of DUNE you will also need
> -</p>
> -<ul>
> -<li>automake (>= 1.9)</li>
> -<li>autoconf (>= 2.62)</li>
> -<li>libtool (>= 2.2)</li>
> -</ul>
> -<p>
> This will provide you with the core DUNE features.</p>
> <p>
> Some DUNE modules might support further software. Using this software
> @@ -53,8 +50,8 @@
> <p>
> To compile the modules DUNE has to check several components of
> your system and whether prerequisites within the modules are met. For
> -the ease of users we have designed a custom build system on top of the
> -automake tools. Run
> +the ease of users we have designed a custom build system on top of
> +CMake. Run
> </p>
> <pre>
> ./dune-common/bin/dunecontrol all
> @@ -63,7 +60,7 @@
> to commence those tests and build all modules you have
> downloaded. Don't worry about messages telling you that libraries are
> missing: they are only needed for grid-self-checks we need for
> -developing.
> +developing or for additional features.
> </p>
> <p>
> You can customize the build to your specific needs by using an options file
> @@ -84,14 +81,14 @@
> part depending on the prefix set)
> </p>
> <p>
> -A more comprehensive introduction to the build system can be found in
> -the <a href="buildsystem/buildsystem.pdf">Dune Build System Howto</a>.
> +The <a href="buildsystem/cmakefaq.pdf">CMake FAQ</a> provides additional
> +helpful informations.
> </p>
>
> <h3>Building a specific DUNE module (and its dependent modules)</h3>
>
> <p>You can instruct dunecontrol to build only a certain dune module,
> -using the <kbd>--only=module_name></kbd> switch.
> +using the <kbd>--only=<module_name></kbd> switch.
> Runnning dunecontrol script
> <p>
> <pre>
> @@ -105,7 +102,7 @@
> <p>If you want to build a module and the modules it depends on, you
> must run:</p>
> <pre>
> -./dune-common/bin/dunecontrol --module=module_name all
> +./dune-common/bin/dunecontrol --module=<module_name> all
> </pre>
> <p> Read <a href="http://dune-project.org/dunemodule.html">Maintaining new Dune modules and applications</a> section for more details.
> </p>
> @@ -118,20 +115,19 @@
> </p>
> <ul>
> <li>
> -autogen (runs autogen in each module, only needed when downloaded
> -via Git)
> +configure (runs the CMake configure tests for each module)
> </li>
> <li>
> -configure (runs the configure tests for each module
> +exec (executes a command in each module directory)
> </li>
> <li>
> -exec (executes a command in each module directory)
> +bexec (executes a command in each module's build directory)
> </li>
> <li>
> make (runs make for each module)
> </li>
> <li>
> -update (updates the Git version)
> +update (pull the latest version from the Git repository)
> </li>
> </ul>
> <p>
> @@ -148,34 +144,15 @@
> <COMMAND_UPPERCASE>_FLAGS=<flags> # e.g.: MAKE_FLAGS=install
> </pre>
> <p>
> -The available options for make are the natural ones. The
> -configure commands available can be found by issuing
> -</p>
> -<pre>
> -dunecontrol --only=dune-common configure --help
> -</pre>
> -<p>
> -and for autogen by
> -</p>
> -<pre>
> -dunecontrol --only=dune-common autogen --help
> -</pre>
> -<p>
> -(In the Git version this has to be called after running autogen.)
> -</p>
> -<p>
> An example of an options file is
> </p>
> <pre>
> - \# use a special compiler (g++ version 3.4) and install to a custom
> + \# use a special compiler (g++ version 5.0) and install to a custom
> \# directory, default is /usr/local/bin
> - CONFIGURE_FLAGS="CXX=g++-3.4 --prefix='/tmp/HuHu'"
> + CMAKE_FLAGS="-DCMAKE_CXX_COMPILER=g++-5 --prefix='/tmp/HuHu'"
> \# Set the default target of make to install. Now the call above will
> \# not just build the DUNE modules but also install it
> MAKE_FLAGS=install
> - \# The default versions of automake and autogen are not sufficient
> - \# therefore we need to specify what versions to use
> - AUTOGEN_FLAGS="--ac=2.59 --am=1.9"
> </pre>
>
> <p>On some platforms special care might have to be taken to make
> @@ -188,7 +165,7 @@
> <p>
> You can create your own dune project module by using the duneproject script available in dune-common/bin directory.
> Running the script will create a directory with supporting files
> -(configure.ac, Makefile.am etc.) and a sample .cc file.
> +(CMakeLists.txt etc.) and a sample .cc file.
> After creating the module you can build this as explained above under "Building a specific DUNE module".
> </p>
> <p>The <a
>
>
> _______________________________________________
> Dune-Commit mailing list
> Dune-Commit at dune-project.org
> http://lists.dune-project.org/mailman/listinfo/dune-commit
>
--
Prof. Dr. Carsten Gräser
Freie Universität Berlin
Institut für Mathematik
Arnimallee 6
14195 Berlin, Germany
phone: +49 30 838 72637
fax : +49 30 838 472637
email: graeser at mi.fu-berlin.de
URL : http://page.mi.fu-berlin.de/graeser
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 473 bytes
Desc: OpenPGP digital signature
URL: <https://lists.dune-project.org/pipermail/dune-devel/attachments/20150916/cb822667/attachment.sig>
More information about the Dune-devel
mailing list