Commit c276879f authored by Steffen Müthing's avatar Steffen Müthing

[Documentation] Add documentation and license info

parent 4bdafdd2
Copyright holders:
2009--2013 Markus Blatt
2009--2013 Christian Engwer
2009--2012 Jorrit Fahlke
2010--2013 Steffen Müthing
2010--2013 Rebecca Neumann
The TypeTree library, headers and test programs are copyrighted free software. You
can use, modify and/or redistribute it under the terms of either one of the two
following licenses:
* The GNU Lesser General Public License as published by the Free Software
Foundation, either Version 3 of the license or (at your option) any later
version. You can find a copy of the GNU Lesser General Public License, Version
3, in the files GPL-3 and LGPL-3 or at <http://www.gnu.org/licenses/lgpl-3.0>.
* Version 2 of the GNU General Public License as published by the Free Software
Foundation, with the following special exception for linking and compiling
against the TypeTree library, the so-called "runtime exception":
As a special exception, you may use the PDELab 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 PDELab source files, or you compile one or more of the PDELab
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.
This license is intended to be similar to the GNU Lesser General Public
License, Version 2, which by itself isn't suitable for a template library. You
can find a copy of the GNU General Public License, Version 2, in the file
GPL-2 or at <http://www.gnu.org/licenses/gpl-2.0>.
This diff is collapsed.
This diff is collapsed.
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
GNU LESSER GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
This version of the GNU Lesser General Public License incorporates
the terms and conditions of version 3 of the GNU General Public
License, supplemented by the additional permissions listed below.
0. Additional Definitions.
As used herein, "this License" refers to version 3 of the GNU Lesser
General Public License, and the "GNU GPL" refers to version 3 of the GNU
General Public License.
"The Library" refers to a covered work governed by this License,
other than an Application or a Combined Work as defined below.
An "Application" is any work that makes use of an interface provided
by the Library, but which is not otherwise based on the Library.
Defining a subclass of a class defined by the Library is deemed a mode
of using an interface provided by the Library.
A "Combined Work" is a work produced by combining or linking an
Application with the Library. The particular version of the Library
with which the Combined Work was made is also called the "Linked
Version".
The "Minimal Corresponding Source" for a Combined Work means the
Corresponding Source for the Combined Work, excluding any source code
for portions of the Combined Work that, considered in isolation, are
based on the Application, and not on the Linked Version.
The "Corresponding Application Code" for a Combined Work means the
object code and/or source code for the Application, including any data
and utility programs needed for reproducing the Combined Work from the
Application, but excluding the System Libraries of the Combined Work.
1. Exception to Section 3 of the GNU GPL.
You may convey a covered work under sections 3 and 4 of this License
without being bound by section 3 of the GNU GPL.
2. Conveying Modified Versions.
If you modify a copy of the Library, and, in your modifications, a
facility refers to a function or data to be supplied by an Application
that uses the facility (other than as an argument passed when the
facility is invoked), then you may convey a copy of the modified
version:
a) under this License, provided that you make a good faith effort to
ensure that, in the event an Application does not supply the
function or data, the facility still operates, and performs
whatever part of its purpose remains meaningful, or
b) under the GNU GPL, with none of the additional permissions of
this License applicable to that copy.
3. Object Code Incorporating Material from Library Header Files.
The object code form of an Application may incorporate material from
a header file that is part of the Library. You may convey such object
code under terms of your choice, provided that, if the incorporated
material is not limited to numerical parameters, data structure
layouts and accessors, or small macros, inline functions and templates
(ten or fewer lines in length), you do both of the following:
a) Give prominent notice with each copy of the object code that the
Library is used in it and that the Library and its use are
covered by this License.
b) Accompany the object code with a copy of the GNU GPL and this license
document.
4. Combined Works.
You may convey a Combined Work under terms of your choice that,
taken together, effectively do not restrict modification of the
portions of the Library contained in the Combined Work and reverse
engineering for debugging such modifications, if you also do each of
the following:
a) Give prominent notice with each copy of the Combined Work that
the Library is used in it and that the Library and its use are
covered by this License.
b) Accompany the Combined Work with a copy of the GNU GPL and this license
document.
c) For a Combined Work that displays copyright notices during
execution, include the copyright notice for the Library among
these notices, as well as a reference directing the user to the
copies of the GNU GPL and this license document.
d) Do one of the following:
0) Convey the Minimal Corresponding Source under the terms of this
License, and the Corresponding Application Code in a form
suitable for, and under terms that permit, the user to
recombine or relink the Application with a modified version of
the Linked Version to produce a modified Combined Work, in the
manner specified by section 6 of the GNU GPL for conveying
Corresponding Source.
1) Use a suitable shared library mechanism for linking with the
Library. A suitable mechanism is one that (a) uses at run time
a copy of the Library already present on the user's computer
system, and (b) will operate properly with a modified version
of the Library that is interface-compatible with the Linked
Version.
e) Provide Installation Information, but only if you would otherwise
be required to provide such information under section 6 of the
GNU GPL, and only to the extent that such information is
necessary to install and execute a modified version of the
Combined Work produced by recombining or relinking the
Application with a modified version of the Linked Version. (If
you use option 4d0, the Installation Information must accompany
the Minimal Corresponding Source and Corresponding Application
Code. If you use option 4d1, you must provide the Installation
Information in the manner specified by section 6 of the GNU GPL
for conveying Corresponding Source.)
5. Combined Libraries.
You may place library facilities that are a work based on the
Library side by side in a single library together with other library
facilities that are not Applications and are not covered by this
License, and convey such a combined library under terms of your
choice, if you do both of the following:
a) Accompany the combined library with a copy of the same work based
on the Library, uncombined with any other library facilities,
conveyed under the terms of this License.
b) Give prominent notice with the combined library that part of it
is a work based on the Library, and explaining where to find the
accompanying uncombined form of the same work.
6. Revised Versions of the GNU Lesser General Public License.
The Free Software Foundation may publish revised and/or new versions
of the GNU Lesser General Public License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the
Library as you received it specifies that a certain numbered version
of the GNU Lesser General Public License "or any later version"
applies to it, you have the option of following the terms and
conditions either of that published version or of any later version
published by the Free Software Foundation. If the Library as you
received it does not specify a version number of the GNU Lesser
General Public License, you may choose any version of the GNU Lesser
General Public License ever published by the Free Software Foundation.
If the Library as you received it specifies that a proxy can decide
whether future versions of the GNU Lesser General Public License shall
apply, that proxy's public statement of acceptance of any version is
permanent authorization for you to choose that version for the
Library.
TypeTree
========
TypeTree is a template library for constructing and operating on statically
typed trees of objects. It is based around the idea of defining loosely coupled,
componentized algorithms. Component lookup happens through tag dispatch, making
it very easy to extend and / or modify existing algorithms as well as constructing
new algorithms for existing types of tree nodes.
The provided algorithms include visitor-based iteration of both single trees and
pairs of trees and a powerful tree transformation algorithm that automatically
decomposes an existing tree and constructs the transformed one, only requiring
the user to specify the per-node transformation policies.
Moreover, there are some more specialized utility algorithms for compile-time
reductions over trees and leaves, which are mainly useful for the construction
of template meta programs.
Finally, there are mixin implementations of the three default node concepts in
the library (leaf nodes, power nodes and composite nodes). For more complicated
use patterns, the library also contains generic implementations of proxy nodes
and, on top of that functionality, filtered nodes that can reorder and / or
restrict access to some of their children.
The TypeTree library was originally developed as part of PDELab[0] to support its
tree-based abstraction of function spaces, but has attracted wider-spread interest.
To facility integration with other projects, we have extracted the code from
PDELab into this standalone library
This package contains the TypeTree library code. For usage examples your best bet
is to look at the PDELab package.
If you have downloaded a release tarball, you can find the autogenerated Doxygen
API documentation in doc/doxygen/html. Otherwise, you can build this documentation
yourself by calling "make doc". Note that you need Doxygen and GraphViz available at
configure time to be able to build the documentation.
If you need help, please ask on the PDELab mailinglist for now [5]. Bugs can also be
submitted to the PDELab bugtracker at [6] instead.
Dependencies
------------
TypeTree depends on the following software packages:
* The dune-common library from DUNE, version 2.3.x. The dependency is actually very
weak, and you can easily use the library standalone by replacing the few convenience
components reused from dune-common (and by replacing the build system, of course).
* TypeTree uses lots and lots of templates, so you need a decent C++ compiler. This
initial release should still compile with GCC 4.2, but we plan to bump up the
requirements to the level of C++11 support provided by GCC 4.4 or 4.5 (not decided
yet). Even now, compile times are greatly reduced if the compiler supports the new
C++11 standard (GCC 4.3 and newer). PDELab is not regularly tested with ICC (it should
work with ICC 13.x), but we also support the clang compiler (3.1+).
For a full explanation of the DUNE installation process please read
the installation notes [2] or the build system HOWTO [3].
License
-------
The PDELab library, headers and test programs are free open-source software,
dual-licensed under version 3 or later of the GNU Lesser General Public License
and version 2 of the GNU General Public License with a special run-time exception.
See the file COPYING for full copying permissions.
Installation
------------
Short installation instructions can be found in file INSTALL. For the
full instructions please see [1].
Links
-----
0. http://www.dune-project.org/pdelab/
1. http://www.dune-project.org
2. http://www.dune-project.org/doc/installation-notes.html
3. http://dune-project.org/doc/buildsystem/buildsystem.pdf
4. http://gcc.gnu.org/onlinedocs/libstdc++/faq.html#faq.license
5. http://lists.dune-project.org/mailman/listinfo/dune-pdelab
6. http://users.dune-project.org/projects/dune-pdelab/issues
Preparing the Sources
=========================
Additional to the software mentioned in README you'll need the
following programs installed on your system:
automake >= 1.5
autoconf >= 2.50
libtool
Getting started
---------------
If these preliminaries are met, you should run
dunecontrol all
which will find all installed dune modules as well as all dune modules
(not installed) which sources reside in a subdirectory of the current
directory. Note that if dune is not installed properly you will either
have to add the directory where the dunecontrol script resides (probably
./dune-common/bin) to your path or specify the relative path of the script.
On your project and all uninstalled DUNE source modules found the script
will then calls the GNU autoconf/automake to create a ./configure-script
and the Makefiles. Afterwards that configure script will be called and the
modules will be build using make all
Most probably you'll have to provide additional information to dunecontrol
(e. g. compilers, configure options) and/or make options.
The most convenient way is to use options files in this case. The files
defining three variables:
AUTOGEN_FLAGS flags passed to autogen
CONFIGURE_FLAGS flags passed to configure
MAKE_FLAGS flags passed to make
An example options file might look like this:
#use this options to autogen, configure and make if no other options are given
AUTOGEN_FLAGS="--ac=2.50 --ac=1.8" #Forces automake 2,50 and autoconf 1.8
CONFIGURE_FLAGS="CXX=g++-3.4 --prefix=/install/path" #force g++-3.4 as compiler
MAKE_FLAGS=install #Per default run make install instead of simply make
If you save this information into example.opts you can path the opts file to
dunecontrol via the --opts option, e. g.
dunecontrol --opts=example.opts all
To get a full list of available configure flags just run
dunecontrol configure --help
after running at least
dunecontrol autogen
More info
---------
See
dunecontrol --help
for further options.
The full build-system is described in the dune-common/doc/buildsystem (SVN version) or under share/doc/dune-common/buildsystem if you installed DUNE!
TypeTree
========
This is the 1.0 release of the TypeTree library for statically typed object trees.
TypeTree 1.0 simply represents the state of the library when it was extracted from
PDELab, only adjusted for the namespace change resulting from the move to a freestanding
library.
Future development will most likely drop support for some of the older compiler still
supported by this release.
Changes
=======
TypeTree 1.0
------------
This is the initial standalone release. It only contains changes due to the extraction
from the PDELab sources.
- Moved headers from dune/pdelab/common/typetree/ to dune/typetree/.
- Changed namespace from Dune::PDELab::TypeTree to Dune::TypeTree.
- Moved tests to top-level directory tests/.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment