From 7f6ee577fafb315fadc38d87cc864ca59d90e2be Mon Sep 17 00:00:00 2001 From: bangerth Date: Fri, 29 Oct 2010 04:03:35 +0000 Subject: [PATCH] Read over it top-to-bottom and bring up to date. git-svn-id: https://svn.dealii.org/trunk@22547 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/doc/readme.html | 314 +++++++++++++++------------------------- 1 file changed, 114 insertions(+), 200 deletions(-) diff --git a/deal.II/doc/readme.html b/deal.II/doc/readme.html index 7d00c4e0a8..c087d8e499 100644 --- a/deal.II/doc/readme.html +++ b/deal.II/doc/readme.html @@ -141,16 +141,21 @@
  • For debugging programs, we have found that the GNU - debugger gdb is a valuable tool. + debugger gdb is a valuable tool. Other options + are DDD + and kdbg, both of + which have graphical user interfaces. Most integrated development + environments like kdevelop or + Eclipse have built + in debuggers as well.

  • - In case you want to generate the documentation from the - header files, you need a copy of doxygen on your machine. Versions 1.4.6 - and later are known to work. If you - have this program, you can generate all the documentation on - your local machine. If not, you can still work with the library and + In case you want to generate the documentation locally on your + machine from the header deal.II files, you need a + copy of doxygen + on your machine. If not, you can still work with the library and use the documentation provided on our homepage for reference. Note that in order to generate inheritance graphs for classes, doxygen can use the dot program, which is part of the -

  • - Doxygen also generates printable API documentation. It is located - in the directories doc/doxygen/LaTeX and - subdirectories. To generate printable versions, you need a latex - installation. However, the present size of this API information is - about 4000 pages, so you may not want to print it, and rather rely - on the online version. The more interesting part of the - documentation to print would probably be the example programs, but - we don't presently have a way to do that apart from printing it - directly from the browser or by using the html2ps - program. -

    -
  • The library generates output in formats readable by GNUPLOT, @@ -186,34 +178,27 @@ and directly to Encapsulated Postscript. GNUPLOT and a postscript viewer (for EPS) should be available almost everywhere. In the last few years, most new visualization - programs have moved to support VTK format, so there are a + programs have moved to support VTK format. There are a number of excellent programs that can read VTK, such as Visit, ParaView, as well as many others. - GMV and Open DX are freely available for most Unix - platforms. Povray is freely available for almost all + target="_top">ParaView, as well as others. + Povray is freely available for almost all platforms. AVS is a commercial program available for most Unix flavors. Tecplot is a commercial program available for - Windows and most Unix platforms. HiVision is available for free after - registration. + Windows and most Unix platforms.

    + +

    + In case you didn't find your favorite graphics format above, adding a new + writer to deal.II is not too difficult as only a + simple + intermediate format needs to be + converted into output (without references to cells, + nodes, types of finite elements, and the like). +

    -

    - In case you didn't find your favorite graphics format above it - might be of interest that it is quite simple to add it to the list - of supported ones (take a look at - base/include/base/data_out_base.h and - base/source/data_out_base.cc to see how output formats are - implemented), as only a simple intermediate format needs to be - converted into a graphics format, without references to cells, - nodes, types of finite elements, and the like. Since your - preferred output format is likely to be similar to one for which - we already have a backend, adaptation is usually simple. In case - you write such a function, we would be happy to integrate it into - the library. -

    @@ -237,22 +222,14 @@

    The most important result of ./configure is the creation of the files common/Make.global_options and - base/include/base/config.h. The first + include/deal.II/base/config.h. The first file contains compiler options, paths, etc which you may want to use in the Makefiles - of your own projects. It is definitely a good - idea to include it into your Makefile, to allow using the same - flags for compilation between library files and the files of your - project, and to access the paths of the library files. To find - out about the supported flags, take a look at the file. Also, - information about Makefiles can be found in the section on + of your own projects. More + information about Makefiles can also be found in the section on development. -

    - -

    - The second generated file contains a number of preprocessor - definitions, that are mostly used to indicate the features and - bugs of the compiler in use. + The second generated file contains preprocessor + definitions that can be used to conditionalize pieces of the source code.

    @@ -265,59 +242,65 @@ ======================================================================== = = = The following targets exist: = - = baseg lacg : debug libraries "base" and "lac" = - = base lac : debug and optimized libraries "base" and "lac" = - = 1dg 2dg 3dg: deal.II debug version for specified dimension = - = 1d 2d 3d : deal.II debug and optimized for specified dimension = + = all : debug and optimized libraries = + = debug : the debug version of the deal.II library = + = optimized : the optimized version of the deal.II library = = = = contrib : additional libraries in contrib, if there are any = = = - = all : base, lac, 1d, 2d and 3d, contrib = - = debug : baseg, lacg, 1dg, 2dg and 3dg, contrib = - = optimized : base, lac, 1d, 2d, and 3d optimized libraries only = - = = = online-doc : generate the documentation in HTML format = = TODO : create a "TODO" file from the source files = = TAGS : create a TAGS file from include and source files = = = - = clean : removes all object files, libraries, etc in subdirs = + = clean : removes all object files in subdirs = + = distclean : removes all object files, libraries, etc in subdirs = ========================================================================

    - To execute one of the commands, type for example `make all'. Building - all libraries takes somewhere between 10 minutes and 1 hour, - depending on your machine and requires about 1.1 GB of free disk - space. If you have a multi-processor machine, you can call `make -j4 - target-name' to let `make' call multiple instances of the compiler - (in this case four). This speeds up compilation by about - the factor given after `-j', at least if you have as many - processors. + To execute one of the commands, type for example make + all. Building all libraries takes somewhere between 4 minutes + and several hours, depending on the number of processors your machine + has, and requires about 2 GB of free disk space. If you have a + multi-processor machine, you can call make -j4 target-name + to let make call multiple instances of the compiler + (in this case four). This speeds up compilation by about + the factor given after -j, at least if you have as many + processors.

    - After `make' has finished, you will have two sets of - libraries. The first consists of the files -

    - Please note that running ./configure stores the paths to some + ./configure stores the paths to some programs, such as the compilers or the Perl interpreter. The compiler which will be used when compiling the library (or your own application) is therefore selected at the time of configuration and independent of the setting of your $PATH environment value at the time when you run make. If you want to change the compiler used, you will therefore have - to re-run ./configure with the new compiler being in the $PATH - environment variable. + to re-run ./configure.

    - It is in general a good idea to run `make clean' + It is in general a good idea to run make clean before re-configuring.

    @@ -532,13 +463,11 @@

    Optional interfaces to other software packages

    deal.II comes with built-in support for a - number of external software packages. These packages are - sometimes detected automatically, sometimes they must be enabled explicitly - during configuration by adding the option --with-package. -

    - -

    These supported software packages comprise (the following list contains - trademarks belonging to their owners): + number of external software packages. These packages are + sometimes detected automatically, sometimes they must be enabled explicitly + during configuration by adding the option --with-package. + Supported software packages are (the following list contains + trademarks belonging to their owners):

    @@ -551,7 +480,7 @@
    UMFPACK
    Enabled by --with-umfpack. If no argument is given, - use the version of UMFPACK that comes bundled with deal.II. If you + use the version of UMFPACK that comes bundled with deal.II. If you want a different version of UMFPACK, provide the path to that version as an argument. Enabling UMFPACK adds the class SparseDirectUMFPACK to the library. The default is to not @@ -659,6 +588,11 @@ avoided by recompiling METIS with -fPIC as a compiler flag.

    + +

    + METIS is not needed when using p4est to parallelize + programs, see below. +

    @@ -773,7 +707,7 @@
    ARPACK
    - There is a wrapper for the + There is a wrapper for the eigenvalue solver ARPACK library, which has its own license; if you want to use it with deal.II, please read it and make sure that you agree with it. @@ -797,26 +731,9 @@ homepage of deal.II, or in the Frequently Asked Questions section. - If you don't find anything there, - feel free to ask if you have any problems with deal.II. If a - question is of general interest, you may want to use our mailing list, - which can be reached at - dealii (at) dealii.org - and of which - - previous mails are also archived online. Before writing to the - list, you will have to subscribe to it. -

    - -

    - You can subscribe to this list by writing email to list-server - (at) dealii.org - with the text (not in the subject!) -

    -      subscribe deal
    -    
    - The list server also understands the command help given - on a line by itself. + If you don't find what you're looking for, + feel free to ask on our + Mailing list.

    @@ -834,6 +751,14 @@ you will be credited for this on our home page.

    +

    + Our institutes are evaluated at regular intervals. Consequently, + we are interested in documenting the use of the programs and + libraries we create. To this end, we collect + publications with results obtained using deal.II. Please + let us know if you have publications that we can add + to this page. +

    License

    @@ -863,28 +788,17 @@ commercially.
  • - Scientific publications presenting results obtained with these - libraries should acknowledge the use of the library and name - its principal authors (at present Wolfgang Bangerth, Ralf - Hartmann and Guido Kanschat). Citation of the reports named on - the homepage is appreciated. + We ask that scientific publications presenting results obtained with this + libraries acknowledge its use. Please cite one of the papers referenced + here. - Note that since our institutes are evaluated at regular intervals, - we are interested in documenting the use of the programs and - libraries we create. We are therefore interested in collecting - publications with results obtained with the aid of these libraries - and would therefore like to ask you to drop us a note about every - such publication. Your publication will then be listed on the - project homepage. -

    - deal.II can interface with a number of other packages that you have to install yourself. They are, of course, covered by their own licenses. In addition, - deal.II comes with a copy of UMFPACK and one of + deal.II comes with copies of UMFPACK and FunctionParser, courtesy of their authors. UMFPACK and FunctionParser are covered by their own licenses; please refer to their webpages to read them. -- 2.39.5