From 6f34f6a3b460405df0bd7a6f80647eecda772649 Mon Sep 17 00:00:00 2001 From: Daniel Arndt Date: Fri, 27 Apr 2018 17:21:09 +0200 Subject: [PATCH] Update readme.html --- doc/readme.html | 1285 ++++++++++++++++++++--------------------------- 1 file changed, 538 insertions(+), 747 deletions(-) diff --git a/doc/readme.html b/doc/readme.html index 93d0841a5e..521b76b73a 100644 --- a/doc/readme.html +++ b/doc/readme.html @@ -2,169 +2,136 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - + + The deal.II Readme - - - - - - - - - - -

Installation instructions and further information - on deal.II

- -
-
    -
  1. System requirements -
      -
    1. Supported platforms
    2. -
    3. Additional software requirements
    4. -
    -
  2. -
  3. Installation -
      -
    1. Unpacking
    2. -
    3. Configuring and building the library
    4. -
    5. Configuring and building the documentation
    6. -
    7. Configuration options -
        -
      1. Selecting optional compilation features
      2. -
      3. Selecting optional library features
      4. -
      5. Optional interfaces to + + + + + + + + + + +

        Installation instructions and further information on deal.II

        + +
        - - -

        System requirements

        - -
        -

        Supported platforms

        - -

        - deal.II is mostly developed on Linux using the - GCC compiler. However, it is not - platform specific and we strive to keep the source code compliant - with the C++ 2011 - Standard (see - also here - for a copy of the C++11 standard). -

        - -

        - deal.II supports at least the following - platforms: -

        -
          -
        • GNU/Linux: GCC version 4.8 or later; Clang version 3.3 or later; - ICC versions 15 or later
        • -
        • Mac OS X: GCC version 4.8 or later; Clang version 3.3 or later. - Please see the deal.II Wiki for installation instructions.
        • -
        • Windows: experimental support for Visual Studio 2017. - Please have a look at the - - FAQ and at the deal.II Wiki for more information and alternative solutions.
        • - -
        - -

        - Most other combinations of POSIX-style operating systems and C++ - Standard compliant compilers should also work. If they don't, +

      +
    8. +
    +
  4. +
  5. License
  6. +
+
+ + +

System requirements

+ +
+

Supported platforms

+ +

+ deal.II is mostly developed on Linux using the + GCC compiler. However, it is not platform specific and we strive to keep the source code compliant with the C++ 2011 + Standard (see also here for a copy of the C++11 standard). +

+ +

+ deal.II supports at least the following platforms: +

+ + +

+ Most other combinations of POSIX-style operating systems and C++ Standard compliant compilers should also work. If they don't, please report it as a bug. -

+

- -

Additional software requirements

+ +

Additional software requirements

- In order to compile and use deal.II - you need to have the following programs installed: + In order to compile and use deal.II you need to have the following programs installed:

@@ -174,161 +141,107 @@

Unpacking

- The whole library usually comes as a tar.gz file, - which is a file archive compressed with gzip. After downloading it, - unpack it using either + The whole library usually comes as a tar.gz file, which is a file archive compressed with gzip. After downloading it, unpack it using either

-
+    
   gunzip deal.II-X.Y.Z.tar.gz
   tar xf deal.II-X.Y.Z.tar
-
-

or, if you have GNU tar with

-
+    
+

or, if you have GNU tar with

+
   tar -xvf deal.II-X.Y.Z.tar.gz
-
+
-

Note: You will want to hang on to the source files - of deal.II after installation as it makes - developing much simpler. Consequently, you should do the steps above - in a permanent directory, not on /tmp as one often does - when installing software. -

+

Note: You will want to hang on to the source files of deal.II after installation as it makes developing much simpler. Consequently, you should do the steps above in a permanent directory, not on /tmp as one often + does when installing software. +

Configuring and building the library

- deal.II uses the - CMake - integrated configuration and build system. Unpacking will create a - subdirectory deal.II/ in the current directory. Then do the - following steps:

+ deal.II uses the + CMake integrated configuration and build system. Unpacking will create a subdirectory deal.II/ in the current directory. Then do the following steps:

-
+    
   mkdir build
   cd build
   cmake -DCMAKE_INSTALL_PREFIX=/path/to/install/dir ../deal.II
   make install
   make test
-
+
-

- These steps compile, link, install the deal.II library, and run a few - consistency checks. The whole process should take between a few minutes - and an hour, depending on your machine. -

+

+ These steps compile, link, install the deal.II library, and run a few consistency checks. The whole process should take between a few minutes and an hour, depending on your machine. +

- Note:

- + Note:

+

- The commands above build and install the deal.II - libraries in two variants: + The commands above build and install the deal.II libraries in two variants:

+
  • +

    Debug mode: This version of the library is compiled with compiler flags so that the library contains information that can be used by debuggers. +

    + +

    + In addition, this library contains a great number of safety checks on most arguments of all functions you could possibly call. These assertions have proven to be an invaluable means to finding programming bugs since they will almost always abort your + program if something goes wrong. In our experience, more than ninety per cent of all errors are invalid parameters (such as vectors having the wrong size, etc.) and they are usually found almost instantaneously, displaying the file name + and line number of where the problem occurred. +

    +

    + With GCC Debug mode, by default, uses the -Og flag. It promises most of the debugging experience of -O0 but at a better performance. This is a reasonable choice for unit tests and enables numerous asserts within + the library. Sometimes, however, one needs Debug mode to use + -O0, where all compiler optimizations are avoided and code and variables are exactly as indicated in the C++ program (e.g. with -Og GCC 6.2.0 optimizes out local variables). This can be achieved by configuring + deal.II with + -DDEAL_II_HAVE_FLAG_Og=false. +

    +
  • + +
  • Optimized mode: You will want to link with this version of the library once you know that your program is working as expected. It does not contain the safety checks any more and is compiled with aggressive compiler optimizations. The resulting + executables are smaller and will run between 2 and 10 times faster than the debug executables. +
  • +

    - At this point, you have generated everything necessary to write - programs based on deal.II. If you are new to - deal.II, you may want to continue with the - tutorial. + At this point, you have generated everything necessary to write programs based on deal.II. If you are new to + deal.II, you may want to continue with the + tutorial.

    Configuring and building the documentation

    - All the documentation about the version that you downloaded and that can - be found at the - http://www.dealii.org/ domain can also be generated locally. To do - so, invoke cmake in the build instructions above as follows: + All the documentation about the version that you downloaded and that can be found at the + http://www.dealii.org/ domain can also be generated locally. To do so, invoke cmake in the build instructions above as follows:

    @@ -336,48 +249,28 @@
         

    - For this to succeed, you will need Perl 5.x, - doxygen - and dot (which is part of - the GraphViz - package) to be installed. + For this to succeed, you will need Perl 5.x, + doxygen and dot (which is part of the GraphViz package) to be installed.

    - The documentation contains links to pictures (e.g., for the - tutorial programs) that are by default stored online at the - dealii.org domain. If you want to use the documentation - completely offline, you can run - the contrib/utilities/makeofflinedoc.sh script in - an installed documentation directory to download all images. + The documentation contains links to pictures (e.g., for the tutorial programs) that are by default stored online at the dealii.org domain. If you want to use the documentation completely offline, you can run the contrib/utilities/makeofflinedoc.sh script in an installed documentation directory to download all images.

    -

    Finally, the default for locally installed documentation is to - render formulas as images. You can force formulas to be - displayed via the MathJax system by - adding -DDEAL_II_DOXYGEN_USE_MATHJAX=ON to the - CMake call above. These formulas are then rendered natively by the - browser. With -DDEAL_II_DOXYGEN_USE_ONLINE_MATHJAX=OFF - CMake will try to find a local installation of MathJax scripts, - otherwise the online version of the scripts will be used in the - documentation. +

    Finally, the default for locally installed documentation is to render formulas as images. You can force formulas to be displayed via the MathJax system by adding -DDEAL_II_DOXYGEN_USE_MATHJAX=ON to the CMake call above. These formulas + are then rendered natively by the browser. With -DDEAL_II_DOXYGEN_USE_ONLINE_MATHJAX=OFF CMake will try to find a local installation of MathJax scripts, otherwise the online version of the scripts will be used in the documentation.

    - Upon calling make and make install, this will - install both this readme, other installation instructions, as well as the - manual that documents - all functions and classes as well as - the tutorial + Upon calling make and make install, this will install both this readme, other installation instructions, as well as the + manual that documents + all functions and classes as well as the tutorial of well-documented example programs (the "steps").

    - Note: Generating this documentation can take a really long - time — running doxygen through our hundreds of thousands of - lines of code can take 15-20 minutes even on a fast machine during which - you will not get any output from make. + Note: Generating this documentation can take a really long + time — running doxygen through our hundreds of thousands of lines of code can take 15-20 minutes even on a fast machine during which you will not get any output from make.

    @@ -385,455 +278,370 @@

    Configuration options

    - deal.II has a large number of optional interfaces to - other libraries. By default, cmake will automatically + deal.II has a large number of optional interfaces to other libraries. By default, cmake will automatically enable support for all external libraries it can find in default - paths. - However, this behavior can be changed using command line switches to - the initial call to cmake. A detailed description - can be found here: Detailed build system description. + paths. However, this behavior can be changed using command line switches to the initial call to cmake. A detailed description can be found here: Detailed build system description.

    - In the following, let us summarize the most common configuration - options. + In the following, let us summarize the most common configuration options.

    - -

    Selecting optional compilation features

    -
    + + +

    Selecting optional library features

    - +

    Optional interfaces to other software packages

    - When configuring interfacing to external libraries, the - cmake script by default tries to find all of these - libraries in a number of standard locations on your file system. - For optional interfaces, it gives up if the library is not - found and deal.II will be built without support - for them. - However, there is one interface that we need to have: BOOST 1.59 or newer. - If it is not found externally cmake will resort to the - bundled boost version that is part of the deal.II - tar file. + When configuring interfacing to external libraries, the + cmake script by default tries to find all of these libraries in a number of standard locations on your file system. For optional interfaces, it gives up if the library is not found and deal.II will be built + without support for them. However, there is one interface that we need to have: BOOST 1.59 or newer. If it is not found externally cmake will resort to the bundled boost version + that is part of the deal.II tar file.

    - The following paragraphs describe how the interfaces to the - various packages, deal.II interacts with, - can be configured. + The following paragraphs describe how the interfaces to the various packages, deal.II interacts with, can be configured.

    Notes:

    -