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: