From: maier Date: Fri, 29 Nov 2013 12:27:53 +0000 (+0000) Subject: Documentation: Some more cleanup X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=dbafc114e7d8587fab339e960b18d255bbfce191;p=dealii-svn.git Documentation: Some more cleanup git-svn-id: https://svn.dealii.org/trunk@31829 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/doc/developers/porting.html b/deal.II/doc/developers/porting.html index 28a71c8fa7..27fbdd8bb9 100644 --- a/deal.II/doc/developers/porting.html +++ b/deal.II/doc/developers/porting.html @@ -40,12 +40,11 @@ To start porting for an unkown compiler, specify -DDEAL_II_SETUP_DEFAULT_COMPILER_FLAGS=OFF and set all necessary compiler flags by hand via - 
-
-    CMAKE_CXX_FLAGS           - used during all builds
-    DEAL_II_CXX_FLAGS_DEBUG   - additional flags for the debug library
-    DEAL_II_CXX_FLAGS_RELEASE - additional flags for the release library
-
+
+CMAKE_CXX_FLAGS           - used during all builds
+DEAL_II_CXX_FLAGS_DEBUG   - additional flags for the debug library
+DEAL_II_CXX_FLAGS_RELEASE - additional flags for the release library
+
After that try to compile the library with minimal external dependencies (-DDEAL_II_ALLOW_AUTODETECTION=OFF, for further information see the deal.II CMake @@ -53,23 +52,21 @@
  • For adding permanent support for the unknown compiler to the build system, have a look at - 
    -
-    cmake/setup_compiler_flags.cmake
-    cmake/setup_compiler_flags_gnu.cmake
-    cmake/setup_compiler_flags_icc.cmake
-
    +
    +cmake/setup_compiler_flags.cmake
+cmake/setup_compiler_flags_gnu.cmake
+cmake/setup_compiler_flags_icc.cmake
+
    Patches are highly welcome! See     here for information on how to get in contact with us.
  • You might want to have a look at - 
    -
-    cmake/checks/check_for_compiler_bugs.cmake
-    cmake/checks/check_for_compiler_features.cmake
-    cmake/checks/check_for_cxx_features.cmake
-    include/deal.II/base/config.h.in
-
    +
    +cmake/checks/check_01_for_compiler_features.cmake
+cmake/checks/check_01_for_cxx_features.cmake
+cmake/checks/check_03_for_compiler_bugs.cmake
+include/deal.II/base/config.h.in
+
    to see how compiler specific checks are done.

    @@ -105,14 +102,13 @@ and Windows and throw a compile time error on other platforms.
  • Have a look at - 
    -
-    cmake/checks/check_for_compiler_bugs.cmake
-    cmake/checks/check_for_compiler_features.cmake
-    cmake/checks/check_for_cxx_features.cmake
-    cmake/checks/check_for_system_features.cmake
-    include/deal.II/base/config.h.in
-
    +
    +cmake/checks/check_for_compiler_bugs.cmake
+cmake/checks/check_for_compiler_features.cmake
+cmake/checks/check_for_cxx_features.cmake
+cmake/checks/check_for_system_features.cmake
+include/deal.II/base/config.h.in
+
    to see how platform and compiler specific checks are done.
  • Of course, we would be happy to hear about the changes you made @@ -148,13 +144,12 @@ (or for for Windows64 using MinGW). After that invoke cmake with something like: - 
    -
-    cmake -DCMAKE_TOOLCHAIN_FILE=<...>/Toolchain.sample
-          -DDEAL_II_FORCE_BUNDLED_BOOST=ON
-          -DDEAL_II_ALLOW_AUTODETECTION=OFF
-          ../deal.II
-
    +
    +$ cmake -DCMAKE_TOOLCHAIN_FILE=<...>/Toolchain.sample \
+        -DDEAL_II_FORCE_BUNDLED_BOOST=ON \
+        -DDEAL_II_ALLOW_AUTODETECTION=OFF \
+        ../deal.II
+
    where CMAKE_TOOLCHAIN_FILE points to the toolchain file. The remaining configuration can be adjusted at will, see the documentation. diff --git a/deal.II/doc/developers/testsuite.html b/deal.II/doc/developers/testsuite.html index a77a74b014..2cbdfad8d8 100644 --- a/deal.II/doc/developers/testsuite.html +++ b/deal.II/doc/developers/testsuite.html @@ -81,18 +81,17 @@

    If you're impatient, use the following commands: - 

    -
-    $ mkdir new_directory
-    $ cd new_directory
-    $ svn checkout https://svn.dealii.org/trunk .
-    $ mkdir build
-    $ cd build
-    $ cmake ../deal.II
-    $ make -j16
-    $ make -j16 setup_tests
-    $ ctest -j16
-
    +
    +$ mkdir new_directory
+$ cd new_directory
+$ svn checkout https://svn.dealii.org/trunk .
+$ mkdir build
+$ cd build
+$ cmake ../deal.II
+$ make -j16
+$ make -j16 setup_tests
+$ ctest -j16
+
    The exact meaning of all of these commands will be explained in much greater detail below.

    @@ -111,19 +110,17 @@ To download the testsuite, check it out from the subversion repository, along with deal.II. To this end, go to an empty directory where you want to test deal.II and do this: - 
    -
-    $ svn checkout https://svn.dealii.org/trunk .
-
    +
    +$ svn checkout https://svn.dealii.org/trunk .
+
    (The period at the end puts everything from under trunk/ into the current directory, rather than creating a new trunk/ directory.) You will then have two folders: - 
    -
-    ./deal.II
-    ./tests
-
    +
    +./deal.II
+./tests
+

    @@ -132,10 +129,9 @@ (../tests). If your test directory is at a different location you have to hint during configuration by specifying TEST_DIR: - 

    -
-    $ cmake -DTEST_DIR=<...>
-
    +
    +$ cmake -DTEST_DIR=<...>
+

    @@ -145,10 +141,9 @@ To enable the testsuite, configure and build deal.II in a build directory as normal (installation is not necessary). After that you can setup the testsuite via the "setup_tests" target:s - 
    -
-    $ make setup_tests
-
    +
    +$ make setup_tests
+
    This will set up all tests supported by the current configuration. The testsuite can now be run in the current build directory as described below. @@ -156,39 +151,37 @@

    Setup can be fine-tuned using the following commands: - 

    +
    +$ make regen_tests - reruns configure stage in every testsuite subproject
 
-    $ make regen_tests - reruns configure stage in every testsuite subproject
+$ make clean_tests - runs the 'clean' target in every testsuite subproject
 
-    $ make clean_tests - runs the 'clean' target in every testsuite subproject
-
-    $ make prune_tests - removes all testsuite subprojects
-      
    
+$ make prune_tests - removes all testsuite subprojects
+

    In addition, when setting up the testsuite, the following environment variables can be used to override default behavior when calling make setup_tests: - 

    -
-    TEST_DIFF
-      - The diff tool and command line to use for comparison. If numdiff is
-        available it defaults to "numdiff -a 1e-6 -q", otherwise plain diff
-        is used.
+
    +TEST_DIFF
+  - The diff tool and command line to use for comparison. If numdiff is
+    available it defaults to "numdiff -a 1e-6 -q", otherwise plain diff
+    is used.
 
-    TEST_TIME_LIMIT
-      - The time limit (in seconds) a single test is allowed to take. Defaults
-        to 180 seconds
+TEST_TIME_LIMIT
+  - The time limit (in seconds) a single test is allowed to take. Defaults
+    to 180 seconds
 
-    TEST_PICKUP_REGEX
-      - A regular expression to select only a subset of tests during setup.
-        An empty string is interpreted as a catchall (this is the default).
+TEST_PICKUP_REGEX
+  - A regular expression to select only a subset of tests during setup.
+    An empty string is interpreted as a catchall (this is the default).
 
-    TEST_OVERRIDE_LOCATION
-      - If TEST_OVERRIDE_LOCATION is set, a comparison file category/test.output
-        will be substituted by ${TEST_OVERRIDE_LOCATION}/category/test.output if
-        the latter exists.
-      
    
+TEST_OVERRIDE_LOCATION
+  - If TEST_OVERRIDE_LOCATION is set, a comparison file category/test.output
+    will be substituted by ${TEST_OVERRIDE_LOCATION}/category/test.output if
+    the latter exists.
+

    @@ -196,10 +189,9 @@

    The testsuite can now be run in the build directory via - 

    -
-    $ ctest [-j N]
-
    +
    +$ ctest [-j N]
+
    Here, N is the number of concurrent tests that should be run, in the same way as you can say make -jN. The testsuite is huge and will need around 12h on current computers @@ -210,11 +202,10 @@ If you only want to run a subset of tests matching a regular expression, or if you want to exclude tests matching a regular expression, you can use - 
    -
-    $ ctest [-j N] -R '<positive regular expression>'
-    $ ctest [-j N] -E '<negative regular expression>'
-
    +
    +$ ctest [-j N] -R '<positive regular expression>'
+$ ctest [-j N] -E '<negative regular expression>'
+

    @@ -236,69 +227,67 @@

    A typical output of a ctest invocation looks like: - 

    -
-    $ ctest -j4 -R "base/thread_validity"
-    Test project /tmp/trunk/build
-          Start 747: base/thread_validity_01.debug
-          Start 748: base/thread_validity_01.release
-          Start 775: base/thread_validity_05.debug
-          Start 776: base/thread_validity_05.release
-     1/24 Test #776: base/thread_validity_05.release ...   Passed    1.89 sec
-     2/24 Test #748: base/thread_validity_01.release ...   Passed    1.89 sec
-          Start 839: base/thread_validity_03.debug
-          Start 840: base/thread_validity_03.release
-     3/24 Test #747: base/thread_validity_01.debug .....   Passed    2.68 sec
-    [...]
-          Start 1077: base/thread_validity_08.debug
-          Start 1078: base/thread_validity_08.release
-    16/24 Test #1078: base/thread_validity_08.release ...***Failed    2.86 sec
-    18/24 Test #1077: base/thread_validity_08.debug .....***Failed    3.97 sec
-    [...]
-
-    92% tests passed, 2 tests failed out of 24
-
-    Total Test time (real) =  20.43 sec
-
-    The following tests FAILED:
-            1077 - base/thread_validity_08.debug (Failed)
-            1078 - base/thread_validity_08.release (Failed)
-    Errors while running CTest
-
    +
    +$ ctest -j4 -R "base/thread_validity"
+Test project /tmp/trunk/build
+      Start 747: base/thread_validity_01.debug
+      Start 748: base/thread_validity_01.release
+      Start 775: base/thread_validity_05.debug
+      Start 776: base/thread_validity_05.release
+ 1/24 Test #776: base/thread_validity_05.release ...   Passed    1.89 sec
+ 2/24 Test #748: base/thread_validity_01.release ...   Passed    1.89 sec
+      Start 839: base/thread_validity_03.debug
+      Start 840: base/thread_validity_03.release
+ 3/24 Test #747: base/thread_validity_01.debug .....   Passed    2.68 sec
+[...]
+      Start 1077: base/thread_validity_08.debug
+      Start 1078: base/thread_validity_08.release
+16/24 Test #1078: base/thread_validity_08.release ...***Failed    2.86 sec
+18/24 Test #1077: base/thread_validity_08.debug .....***Failed    3.97 sec
+[...]
+
+92% tests passed, 2 tests failed out of 24
+
+Total Test time (real) =  20.43 sec
+
+The following tests FAILED:
+        1077 - base/thread_validity_08.debug (Failed)
+        1078 - base/thread_validity_08.release (Failed)
+Errors while running CTest
+
    If a test failed (like base/thread_validity_08.debug in above example output), you might want to find out what exactly went wrong. To this end, you can search through Testing/Temporary/LastTest.log for the exact output of the test, or you can rerun this one test, specifying -V to select verbose output of tests: - 
    -
-    $ ctest -V -R "base/thread_validity_08.debug"
-    [...]
-    test 1077
-        Start 1077: base/thread_validity_08.debug
-
-    1077: Test command: [...]
-    1077: Test timeout computed to be: 600
-    1077: Test base/thread_validity_08.debug: RUN
-    1077: ===============================   OUTPUT BEGIN  ===============================
-    1077: Built target thread_validity_08.debug
-    1077: Generating thread_validity_08.debug/output
-    1077: terminate called without an active exception
-    1077: /bin/sh: line 1: 18030 Aborted [...]/thread_validity_08.debug
-    1077: base/thread_validity_08.debug: BUILD successful.
-    1077: base/thread_validity_08.debug: RUN failed. Output:
-    1077: DEAL::OK.
-    1077: gmake[3]: *** [thread_validity_08.debug/output] Error 1
-    1077: gmake[2]: *** [CMakeFiles/thread_validity_08.debug.diff.dir/all] Error 2
-    1077: gmake[1]: *** [CMakeFiles/thread_validity_08.debug.diff.dir/rule] Error 2
-    1077: gmake: *** [thread_validity_08.debug.diff] Error 2
-    1077:
-    1077:
-    1077: base/thread_validity_08.debug: ******    RUN failed    *******
-    1077:
-    1077: ===============================    OUTPUT END   ===============================
-
    +
    +$ ctest -V -R "base/thread_validity_08.debug"
+[...]
+test 1077
+    Start 1077: base/thread_validity_08.debug
+
+1077: Test command: [...]
+1077: Test timeout computed to be: 600
+1077: Test base/thread_validity_08.debug: RUN
+1077: ===============================   OUTPUT BEGIN  ===============================
+1077: Built target thread_validity_08.debug
+1077: Generating thread_validity_08.debug/output
+1077: terminate called without an active exception
+1077: /bin/sh: line 1: 18030 Aborted [...]/thread_validity_08.debug
+1077: base/thread_validity_08.debug: BUILD successful.
+1077: base/thread_validity_08.debug: RUN failed. Output:
+1077: DEAL::OK.
+1077: gmake[3]: *** [thread_validity_08.debug/output] Error 1
+1077: gmake[2]: *** [CMakeFiles/thread_validity_08.debug.diff.dir/all] Error 2
+1077: gmake[1]: *** [CMakeFiles/thread_validity_08.debug.diff.dir/rule] Error 2
+1077: gmake: *** [thread_validity_08.debug.diff] Error 2
+1077:
+1077:
+1077: base/thread_validity_08.debug: ******    RUN failed    *******
+1077:
+1077: ===============================    OUTPUT END   ===============================
+
    So this specific test aborted in the RUN stage.

    @@ -306,25 +295,23 @@ The general output for a successful test <test> in category <category> for build type <build> is - 
    -
-    xx: Test <category>/<test>.<build>: PASSED
-    xx: ===============================   OUTPUT BEGIN  ===============================
-    xx: [...]
-    xx: <category>/<test>.<build>: PASSED.
-    xx: ===============================    OUTPUT END   ===============================
-
    +
    +xx: Test <category>/<test>.<build>: PASSED
+xx: ===============================   OUTPUT BEGIN  ===============================
+xx: [...]
+xx: <category>/<test>.<build>: PASSED.
+xx: ===============================    OUTPUT END   ===============================
+
    And for a test that fails in stage <stage>: - 
    -
-    xx: Test <category>/<test>.<build>: <stage>
-    xx: ===============================   OUTPUT BEGIN  ===============================
-    xx: [...]
-    xx: <category>/<test>.<build>: <stage> failed. [...]
-    xx:
-    xx: <category>/<test>.<build>: ******    <stage> failed    *******
-    xx: ===============================    OUTPUT END   ===============================
-
    +
    +xx: Test <category>/<test>.<build>: <stage>
+xx: ===============================   OUTPUT BEGIN  ===============================
+xx: [...]
+xx: <category>/<test>.<build>: <stage> failed. [...]
+xx:
+xx: <category>/<test>.<build>: ******    <stage> failed    *******
+xx: ===============================    OUTPUT END   ===============================
+
    Hereby, <stage> indicates the stage in which the test failed: