From: maier Date: Thu, 28 Mar 2013 16:17:07 +0000 (+0000) Subject: Update documentation X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9b13a31976f5ac5df81db99072a4b5d10090b855;p=dealii-svn.git Update documentation git-svn-id: https://svn.dealii.org/trunk@29101 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/cmake/TODO.CMAKE b/deal.II/cmake/TODO.CMAKE index 6b5c2e5627..06979ce6c8 100644 --- a/deal.II/cmake/TODO.CMAKE +++ b/deal.II/cmake/TODO.CMAKE @@ -1,7 +1,5 @@ Major: -* Mumps may have a transitive link interface to Scotch. Fix this - * Get rid of the last bits of unguarded platform introspection Some last bits and thoughts: @@ -14,8 +12,4 @@ Some last bits and thoughts: * document that we no longer need the two-lib installation of p4est -* adjust doc/development/testsuite.html - -* update https://code.google.com/p/dealii/wiki/Windows - * same for the Mac part... diff --git a/deal.II/doc/development/testsuite.html b/deal.II/doc/development/testsuite.html index a427b87424..d9a5d3c7de 100644 --- a/deal.II/doc/development/testsuite.html +++ b/deal.II/doc/development/testsuite.html @@ -29,96 +29,71 @@

The build tests

-

With our build tests, we check if deal.II can be compiled on - different systems and with different compilers as well as - different configuration options. Results are collected in a - database and can be accessed online.

- -

Running the build test suite is simple and we encourage deal.II - users with configurations not found on the test suite page to - participate. Assuming you checked out deal.II into the directory - dealtest, running it is as simple as (you may want to pass - different options than the ones given as BUILDTESTFLAGS to - ./configure):

- -
+    

+ With our build tests, we check if deal.II can be compiled on + different systems and with different compilers as well as + different configuration options. Results are collected in a + database and can be accessed online.

+ +

Running the build test suite is simple and we encourage deal.II + users with configurations not found on the test suite page to + participate. Assuming you checked out deal.II into the directory + dealtest, running it is as simple as: +

 
     cd dealtest
-    make distclean
     svn update
-    make build-test BUILDTESTFLAGS='--with-umfpack --with-lapack'
-    mail build-tests@dealii.org < build-test-log
-
-    
- -

After cleaning up the directory and updating the library to the - most recent version, the make command configures the - library (here for use of UMFPack and LAPACK libraries) and - compiles everything. The result is in the file - build-test-log, which is sent to the build test demon - in the end. A status indicator should appear on the build test website - after some time (results are collected and processed by a program that is - run periodically, but not immediately after a mail has been received). + ./contrib/utilities/build_test + mail build-tests@dealii.org < *.log + ( rm *.log ) +

-

Configuring for a special compiler

- -

If your compiler is not in the standard path or has a strange - name (like mycc for C and myCC for C++), - your template would be something like this (assuming you work with the - bash shell):

- -
-
-    export PATH=/my/compiler/path:$PATH
-    export CXX=myCC
-
-    cd dealtest
-    make clean
-    svn update
-    make build-test BUILDTESTFLAGS='CC=mycc CXX=myCC'
-    mail build-tests@dealii.org < build-test-log
-
-    
- - -

Dedicated tests

-

- Most of our tests are built in dedicated directories, i.e. work on copies - of deal.II that we don't usually use to work on every day. We do this, - because we want to see if the version in the subversion repository can be - compiled, not the version that we have made changes in. + The build_test script supports the following options: +

+
+    SOURCEDIR     - the source directory to use (otherwise the current directory is used)
+    CONFIGFILE    - A cmake configuration file for the build test
+    LOGDIR        - directory for the log file
+    LOGFILE       - the logfile to use, defaults to
+                        $LOGDIR/$BRANCH.$CONFIGFILE..log
+
+    CMAKE         - the cmake executable to use
+    SVN           - svn info command to use, defaults to
+                        svn info $(SOURCEDIR)
+    TMPDIR        - defaults to "/tmp"
+    CLEAN_TMPDIR  - defaults to "true"
+    RUN_EXAMPLES  - defaults to "true"
+      
+ An example configuration file can be found here. Options can be passed either via + environment +
+
+    export CONFIGFILE=MyConfiguration.conf
+    ./contrib/utilities/build_test
+      
+ or directly on the command line: +
+
+    ./contrib/utilities/build_test CONFIGFILE=myConfiguration.conf
+      

- In this case, one would check out a new version, and do essentially the - same things as above: - -

-
-    export PATH=/my/compiler/path:$PATH
-    export CXX=myCC
-
-    svn co https://svn.dealii.org/trunk/deal.II
-    cd deal.II
-    svn update
-    make build-test BUILDTEST=yes BUILDTESTFLAGS='CC=mycc CXX=myCC'
-    mail build-tests@dealii.org < build-test-log
-    cd ..
-    rm -rf deal.II
+      A status indicator should appear on the build test website after some
+      time (results are collected and processed by a program that is run
+      periodically, but not immediately after a mail has been received).
+    

-
- The only difference is that one has to give the option - BUILDTEST=yes to the call to make. This is so - because for the make file to work it depends on a file that is created by - ./configure; the latter, however, hasn't run on this pristine - copy yet. -

+

Dedicated build tests

+ There is a detailed example for dedicated build tests on the wiki.

The regression tests

@@ -153,6 +128,7 @@ To run the testsuite, go to the directory where you want to test deal.II and do this:
+
        svn checkout https://svn.dealii.org/trunk/tests
        cd tests
        DEAL_II_DIR=/a/b/c ./configure
@@ -182,6 +158,7 @@
     archive. This is helpful if you want to figure out if any test is
     failing at all. Typical output looks like this:
     
+
       deal.II/tests> make
       cd base ; make
       make[1]: Entering directory `/ices/bangerth/p/deal.II/1/deal.II/tests/base'
@@ -221,10 +198,12 @@
     (the same applies as above: make -jN can be used on multicore
     machines):
     
+
       deal.II/tests> make report | tee report
     
which produces the file report ( here in the test directory a-framework)
+
       =====Checking====== miscompare/output
       +++++Error+++++++++ miscompare/OK (miscompare/cmp/generic) Use make verbose=on for the diffs
       =====linking======= compile/exe
@@ -256,6 +235,7 @@
     If you only want to see the tests that failed, after the previous command,
     issue
     
+
       grep -v + report
     

@@ -264,6 +244,7 @@ If you want to do a little more than just that, you should consider running
+
       make report+mail | tee report
     
instead. This does all the same stuff, but also mails the test @@ -279,11 +260,13 @@

To get a quick overview you can run

+
       make report+summary
     
instead. This runs all the tests and outputs a table in the following format at the end:
+
                 Compiling Linking Running   Check      OK     all
          a-framework	1	1	1	1	1	5
                 base	0	0	0	2	185	187
@@ -305,6 +288,7 @@
     given in the line with the equals signs; there are tests in other
     directories as well) and then type
     
+
       make hierarchical/exe
     
to compile and link the executable. (For each test there is a not @@ -316,6 +300,7 @@ the test, you will want to make sure that it executes correctly and produces an output file:
+
       make hierarchical/output
     
(As you see, the output file is also stored in the subdirectory with the @@ -324,11 +309,13 @@ the other hand, if you are sure that this also worked, you will want to compare the output with the stored output from subversion:
+
       make hierarchical/OK
     
If the output isn't equal, then you'll see something like this:
+
       =====Checking====== hierarchical/output
       +++++Error+++++++++ hierarchical/OK. Use make verbose=on for the diffs
     
@@ -336,10 +323,12 @@ expected can sometimes be very large, you don't get to see it by default. However, following the suggestion printed, if you type
+
       make hierarchical/OK verbose=on
     
you get to see it all:
+
       =====Checking====== hierarchical/output
       12c12
       < DEAL::0.333 1.667 0.333 -0.889 0.296 -0.988 0.329 -0.999 0.333 -1.000 0.333 -1.000
@@ -370,6 +359,7 @@
     

For the testcase, we usually start from a template like this:

+
 //----------------------------  my_new_test.cc  ---------------------------
 //    $Id$
 //
@@ -446,12 +436,14 @@ int main ()
     

One convenient way to create this subdirectory with the correct properties is to use svn copy.

+
     svn copy existing_test_directory my_new_test
     

Once you have done this, you can try to run

+
       make my_new_test/output
     
This should compile, link, and run your test. Running your test @@ -507,6 +499,7 @@ int main () gcc4.0 as your compiler, then the following files will be sought (in this order):
+
 testname/cmp/i686-pc-linux-gnu+gcc4.0
 testname/cmp/i686-pc-linux-gnu+gcc3.4
 testname/cmp/i686-pc-linux-gnu+gcc3.3
@@ -532,6 +525,7 @@ testname/cmp/generic
     

At this point you can run

+
       make my_new_test/OK
     
which should compare the present output with what you have just @@ -548,6 +542,7 @@ testname/cmp/generic testname/cmp/myplatform+compiler, but your life can be easier if you simply type
+
       make my_new_test/ref
     
which takes your output and copies it to the right place automatically. @@ -565,6 +560,7 @@ testname/cmp/generic already, you can add the new test and the expected output file:
+
       svn add bits/my_new_test.cc
       svn add bits/my_new_test
       svn add bits/my_new_test/cmp
@@ -575,6 +571,7 @@ testname/cmp/generic
     generated while running the testsuite show up in the output of svn
     status commands:
     
+
       svn propset svn:ignore "obj.*
         exe
         output