merged seperation of installation instructions from trunk r4879:4880

[[Imported from SVN: r4881]]

INSTALL

-hier soll stehen wie man mit configure und automake installiert
+Installation Instructions
+=========================
+
+For a full explanation of the DUNE installation process please read
+the installation notes [0]. The following introduction is meant for
+the impatient.
+
+Getting started
+---------------
+
+Suppose you have downloaded all DUNE modules of interest to your
+computer and extracted then in one common directory. See [1] for a
+list of available modules.
+
+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
+
+  ./dune-common/bin/dunecontrol all
+
+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.
+
+You can customize the build to your specific needs by using an options file
+(see below)
+
+  ./dune-common/bin/dunecontrol --opts=/path_to/file.opts
+
+If you did not tell dunecontrol to install with an options file you
+need to run
+
+  ./dune-common/bin/dunecontrol make install
+
+to install Dune (you may need root-permissions for the install
+part depending on the prefix set)
+
+A more comprehensive introduction to the build system can be found in [2].
+
+Passing options to the build process
+------------------------------------
+
+Using the dunecontrol script the following atomic commands can be
+executed:
+
+- autogen (runs autogen in each module, only needed when downloaded
+  via svn)
+- configure (runs the configure tests for each module
+- exec (executes a command in each module directory)
+- make (runs make for each module)
+- update (updates the svn version)
+
+The composite command all simply runs autogen, configure and make for
+each module.
+
+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 --opts=<file>
+option. For each atomic command one specify the options via a ine
+
+<COMMANY_UPPERCASE>_FLAGS=<flags> # e.g.: MAKE_FLAGS=install
+
+The available options for make and svn are the natural ones. The
+configure commands available can be found by issuing
+
+dunecontrol --only=dune-common configure --help
+
+and for autogen by
+
+dunecontrol --only=dune-common autogen --help
+
+(In the svn version this has to be calles after running autogen.)
+
+
+An example of an options file is
+
+  # 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/Hu Hu'"
+  # 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
+
+Links
+-----
+
+0. http://www.dune-project.org/doc/installation-notes.html
+1. http://www.dune-project.org/download.html
+2. http://dune-project.org/doc/buildsystem/buildsystem.pdf

README

 DUNE-library
 ============
 
+DUNE, the Distributed and Unified Numerics Environment is a modular toolbox
+for solving partial differential equations with grid-based methods.
+.
+The main intention is to create slim interfaces allowing an efficient use of
+legacy and/or new libraries. Using C+techniques DUNE allows to use very
+different implementation of the same concept (i.e. grid, solver, ...) under
+a common interface with a very low overhead.
 
-For a full explanation of the DUNE installation process please read
-the installation notes [0]. The following introduction is meant for
-the impatient.
-
-Getting started
----------------
-
-Suppose you have downloaded all DUNE modules of interest to you and
-extracted then in one common directory. See [1] for a list of
-available modules.
-
-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
-
-  ./dune-common/bin/dunecontrol all
-
-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.
+DUNE was desined with flexibility in mind. It supports easy discretization
+using methods, like Finite Elements, Finite Volume and also Finite
+Differences. Through speration of data structures DUNE allows fast Linear
+Algebra like provided in the ISTL module, or usage of external libraries
+like blas.
 
-You can customize the build to your specific needs by using an options file
+This package contains the basic DUNE common classes.
 
-  ./dune-common/bin/dunecontrol --opts=/path_to/file.opts
+Dependencies
+------------
 
-An example of an options file is
+dune-common depends on the following software packages
 
-  # 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/Hu Hu'"
-  # 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
+- pkg-config
+- icc (C/C++) >= 7.0 or GNU C, C++ >=3.4
 
-If you did not tell dunecontrol to install with an options file you
-need to run
+The following software is recommend but optional:
 
-  ./dune-common/bin/dunecontrol make install
+- MPI (either OpenMPI, lam, or mpich suffice)
 
-to install Dune (you may need root-permissions for the install
-part depending on the prefix set)
-
-A more comprehensive introduction to the build system can be found in [2].
+For a full explanation of the DUNE installation process please read
+the installation notes [0]. The following introduction is meant for
+the impatient.
 
 License
 -------
 
-The DUNE library and headers are licensed under version 2 of the GNU
-General Public License, with a special exception for linking and
-compiling against DUNE, the so-called "runtime exception."  The
-license is intended to be similiar to the GNU Lesser General Public
-License, which by itself isn't suitable for a template library.
-
-The exact wording of the exception reads as follows:
-
-   As a special exception, you may use the DUNE source files as part
-   of a software library or application without restriction.
-   Specifically, if other files instantiate templates or use macros or
-   inline functions from one or more of the DUNE source files, or you
-   compile one or more of the DUNE source files and link them with
-   other files to produce an executable, this does not by itself cause
-   the resulting executable to be covered by the GNU General Public
-   License.  This exception does not however invalidate any other
-   reasons why the executable file might be covered by the GNU General
-   Public License.
+The Dune-library and headers are licensed under version 2 of the GNU
+General Public License, with the so-called "runtime exception," as
+follows:
+
+   As a special exception, you may use the DUNE source files as part of a
+   free software library without restriction.  Specifically, if other
+   files instantiate templates or use macros or inline functions
+   from one or more of the DUNE source file, or you compile one or
+   more of the DUNE source files and link them with other files to
+   produce an executable, this the DUNE source files used do  not by
+   themselves cause the resulting executable to be covered by the GNU
+   General Public License.  This exception does not however invalidate
+   any other reasons why the executable file might be covered by
+   the GNU General Public License.
 
 This licence clones the one of the libstc++ library. For further
-implications please see the licence page of libstdc++ [3].  For the
-complete text of the GNU GPL see the COPYING file in this directory.
+implications of this library please see their licence page [3]
+
+See the file COPYING for full copying permissions.
+
+Installation
+------------
+
+Short installation instructions can be found in file INSTALL. For the
+full instructions please see [0].
 
 Links
 -----

README.SVN

-Preparing the CVS-sources
+Preparing the SVN-sources
 =========================
 
 Additional to the software mentioned in README you'll need the
@@ -10,89 +10,19 @@ following programs installed on your system:
 
   libtool
 
-For the documentation to build you'll need doxygen and latex
+For the documentation to build you'll need doxygen, wml, convert and latex
 installed.
 
 Dune also features a self-test. As some grid-components (e.g. Albert,
 UG) depend on external libraries their self-tests will only run if
 those libraries are found. The pathes would then need to be passed via
---with-...= parameters. 
+--with-...= parameters.
 
 Important!  If you don't want to develop Dune itself you won't need to
 provide external components! The Dune-library and -headers are
 independent of other libraries, instead the applications can choose
 what parts to use.
 
-Getting started
----------------
-
-If these preliminaries are met, you should run the script
-
-  ./autogen.sh
-
-which calls the GNU autoconf/automake to create a ./configure-script
-and the Makefiles. The configure-script is automatically called and
-you're ready to perform a
-
-  make
-
-to build the library and documentation. Dune can be installed into
-your system via
-
-  make install
-
-You can provide a --prefix=PATH parameter to autogen to install the
-components into PATH/lib, PATH/include, ... instead of the default
-/usr/local/lib, /usr/local/include
-
-Passing options to ./configure
-------------------------------
-
-autogen.sh also calls the newly created configure-script to
-conveniently pass on options about the used compiler. Thus you'll have
-to provide autogen.sh any options you want configure to get, e.g.
-
-  ./autogen.sh --with-albert=... --with-ug=...
-
-
-Choosing the compiler and the options
--------------------------------------
-
-The selection of the compiler works as follows: if --gnu or --intel is
-passed to autogen it reads the content of gcc.opts or icc.opts to get
-the default compiler flags. With the option --optim you can switch the
-compiler-specific optimization parameters on.
-
-If you want to change the compiler options to your favourites you can
-either
-
- - adapt the appropriate .opts-file and rerun autogen.sh. Please don't
-   commit this changed file to CVS if you're not sure if the options
-   work for everybody.
-
- - copy an existing .opts-file to a new name, change the options and
-   use
-
-      ./autogen.sh --opts=my.opts
-
-
-More info
----------
-
-See
-
-     ./autogen.sh --help
-   
-and (if it exists)
- 
-     ./configure --help
-
-for further options.
-
-
-The full build-system is described in the doc/Buildsystem
-
-
 $Id$