From 5c4c4989cea566fa035a2fef0b29c116fe3907be Mon Sep 17 00:00:00 2001 From: maier Date: Sun, 13 Oct 2013 16:21:18 +0000 Subject: [PATCH] Finish documentation git-svn-id: https://svn.dealii.org/branches/branch_port_the_testsuite@31215 0785d39b-7218-0410-832d-ea1e28bc413d --- .../cmake/scripts/run_buildtest.cmake | 0 deal.II/cmake/scripts/run_testsuite.cmake | 16 +- deal.II/doc/developers/testsuite.html | 144 ++++++++++++------ tests/run_buildtest.cmake | 2 + tests/run_testsuite.cmake | 13 ++ 5 files changed, 115 insertions(+), 60 deletions(-) rename tests/run_buildtests.cmake => deal.II/cmake/scripts/run_buildtest.cmake (100%) create mode 100644 tests/run_buildtest.cmake diff --git a/tests/run_buildtests.cmake b/deal.II/cmake/scripts/run_buildtest.cmake similarity index 100% rename from tests/run_buildtests.cmake rename to deal.II/cmake/scripts/run_buildtest.cmake diff --git a/deal.II/cmake/scripts/run_testsuite.cmake b/deal.II/cmake/scripts/run_testsuite.cmake index 89dae024aa..6e496b0b55 100644 --- a/deal.II/cmake/scripts/run_testsuite.cmake +++ b/deal.II/cmake/scripts/run_testsuite.cmake @@ -118,16 +118,10 @@ MESSAGE("-- TRACK: ${TRACK}") IF("${CTEST_SOURCE_DIRECTORY}" STREQUAL "") # # If CTEST_SOURCE_DIRECTORY is not set we just assume that this script - # was called residing under (a) ../tests relative to the source directory - # or (b) cmake/scipts in the source directory + # was called residing under cmake/scipts in the source directory # GET_FILENAME_COMPONENT(_path "${CMAKE_CURRENT_LIST_DIR}" PATH) - SET(CTEST_SOURCE_DIRECTORY ${_path}/deal.II) - - IF(NOT EXISTS ${CTEST_SOURCE_DIRECTORY}/CMakeLists.txt) - GET_FILENAME_COMPONENT(_path "${_path}" PATH) - SET(CTEST_SOURCE_DIRECTORY ${_path}) - ENDIF() + GET_FILENAME_COMPONENT(CTEST_SOURCE_DIRECTORY "${_path}" PATH) IF(NOT EXISTS ${CTEST_SOURCE_DIRECTORY}/CMakeLists.txt) MESSAGE(FATAL_ERROR " @@ -159,8 +153,7 @@ IF("${CTEST_BINARY_DIRECTORY}" STREQUAL "") # SET(CTEST_BINARY_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}) - IF( "${CTEST_BINARY_DIRECTORY}" STREQUAL "${CTEST_SOURCE_DIR}" - OR "${CTEST_BINARY_DIRECTORY}" STREQUAL "${CMAKE_CURRENT_LIST_DIR}" ) + IF( "${CTEST_BINARY_DIRECTORY}" STREQUAL "${CTEST_SOURCE_DIRECTORY}") MESSAGE(FATAL_ERROR " ctest was invoked in the source directory (or test source directory) and CTEST_BINARY_DIRECTORY is not set. Please either call ctest from within a designated build directory, or set CTEST_BINARY_DIRECTORY accordingly. @@ -230,7 +223,6 @@ SET(CTEST_SITE "${_hostname}") MESSAGE("-- CTEST_SITE: ${CTEST_SITE}") -ENDIF() IF( "${TRACK}" STREQUAL "Regression Tests" AND NOT CTEST_SITE MATCHES "c0541" ) MESSAGE(FATAL_ERROR " @@ -462,4 +454,4 @@ ENDIF() CTEST_SUBMIT() -# .oO( This script is freaky 461 lines long... ) +# .oO( This script is freaky 457 lines long... ) diff --git a/deal.II/doc/developers/testsuite.html b/deal.II/doc/developers/testsuite.html index 5c22d9454c..754e765dc3 100644 --- a/deal.II/doc/developers/testsuite.html +++ b/deal.II/doc/developers/testsuite.html @@ -79,6 +79,7 @@

If you're impatient, use the following commands: 

+
     $ mkdir new_directory
     $ cd new_directory
     $ svn checkout https://svn.dealii.org/trunk .
@@ -526,6 +527,7 @@
       and modify it to where it does what we'd like to test. Alternatively,
       you can also start from a template like this:
     
+
 // ---------------------------------------------------------------------
 // $Id$
 //
@@ -661,9 +663,82 @@ int main ()
     
     
Submitting test results

 
-    

-      Explain how to use run_testsuite.cmake in all imaginable
-      ways...
+    

+      To submit test results to our CDash
+      instance just invoke ctest within a build directory (or designated
+      build directory) with the -S option pointing to the
+      run_testsuite.cmake script: 
+
+      $ ctest [...] -V -S ../tests/run_testsuite.cmake
+      

+      The script will run configure, build and ctest and submit the results
+      to the CDash server. It does not matter whether the configure, build
+      or ctest stages were run before that. Also in script mode, you can
+      specify the same options for ctest as explained above.
+    

+
+    

+      Note: The default output in script mode is very minimal.
+      Therefore, it is recommended to specify -V which will
+      give the same level of verbosity as the non-script mode.
+    

+
+    

+      Note: The following variables can be set to via
+      
+
+    ctest -D<variable>=<value> [...]
+      

+      to control the behaviour of the run_testsuite.cmake
+      script:
+      
+
+    CTEST_SOURCE_DIRECTORY
+      - The source directory of deal.II (usually ending in "[...]/deal.II"
+        (equivalent to https://svn.dealii.org/trunk/deal.II)
+        Note: This is _not_ the test directory ending in "[...]/tests"
+      - If unspecified, "../deal.II" and "../../$ relative to the location
+        of this script is used. If this is not a source directory, an error
+        thrown.
+
+    CTEST_BINARY_DIRECTORY
+      - The designated build directory (already configured, empty, or non
+        existent - see the information about TRACKs what will happen)
+      - If unspecified the current directory is used. If the current
+        directory is equal to CTEST_SOURCE_DIRECTORY or the "tests"
+        directory, an error is thrown.
+
+    CTEST_CMAKE_GENERATOR
+      - The CMake Generator to use (e.g. "Unix Makefiles", or "Ninja", see
+        $ man cmake)
+      - If unspecified the current generator of a configured build directory
+        will be used, otherwise "Unix Makefiles".
+
+    TRACK
+      - The track the test should be submitted to. Defaults to "Experimental".
+        Possible values are:
+
+        "Experimental"     - all tests that are not specifically "build" or
+                             "regression" tests should go into this track
+
+        "Build Tests"      - Build tests that configure and build in a
+                             clean directory and run the build tests
+                             "build_tests/*"
+
+        "Nightly"          - Reserved for nightly regression tests for
+                             build bots on various architectures
+
+        "Regression Tests" - Reserved for the regression tester
+
+    CONFIG_FILE
+      - A configuration file (see docs/development/Config.sample)
+        that will be used during the configuration stage (invokes
+        $ cmake -C ${CONFIG_FILE}). This only has an effect if
+        CTEST_BINARY_DIRECTORY is empty.
+      

+      Furthermore, the variables described above can also be
+      set and will be handed automatically down to cmake.
     

 
 
@@ -674,70 +749,43 @@ int main ()
     

       Build tests are used to check that 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.

+      different configuration options. Results are collected in the "Build
+      Tests" track in CDash.

 
       
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:
+      deal.II, running it is as simple as:
       
 
-    cd dealtest
-    svn update
-    ./contrib/utilities/build_test
-    mail build-tests@dealii.org < *.log
-  ( rm *.log )
+    cd deal.II
+    mkdir build
+    cd build
+    ctest -j4 -S ../cmake/scripts/run_buildtest.cmake
       

     

 
     

-      What this does is to create a temporary directory, compile and build
-      deal.II in it, and for good measure also build the tutorial
-      programs. The fourth of the commands above then sends the resulting
-      status files to a daemon that presents this information on the website
-      linked to above.
+      What this does is to compile and build deal.II in the directory
+      build, try to configure, build (and run a subset) of all
+      tutorial programs supported by the current configuration and send the
+      results to the CDash instance.
     

 
     

-      The build_test script supports the following options:
+      Note: Build tests require the designated build directory to be
+      completely empty and the source directory to be under subversion
+      version control. If you want to specify a build configuration for
+      cmake use a configuration file
+      to preseed the cache as explained above:
       
 
-    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 variables
-      
-
-    export CONFIGFILE=MyConfiguration.conf
-    ./contrib/utilities/build_test
-      

-      or directly on the command line:
-      
-
-    ./contrib/utilities/build_test CONFIGFILE=myConfiguration.conf
+    $ ctest -DCONFIG_FILE="[...]/Config.sample" [...]
       

     

 
-    

-      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).
-    

 
 
     
diff --git a/tests/run_buildtest.cmake b/tests/run_buildtest.cmake
new file mode 100644
index 0000000000..98014f1de8
--- /dev/null
+++ b/tests/run_buildtest.cmake
@@ -0,0 +1,2 @@
+SET(TRACK "Build Tests")
+INCLUDE(${CMAKE_CURRENT_LIST_DIR}/run_testsuite.cmake)
diff --git a/tests/run_testsuite.cmake b/tests/run_testsuite.cmake
index 51f970e900..6723f32917 100644
--- a/tests/run_testsuite.cmake
+++ b/tests/run_testsuite.cmake
@@ -14,6 +14,19 @@
 ##
 ## ---------------------------------------------------------------------
 
+#
+# Sanity check: Do not run the testsuite within a test directory
+#
+
+IF( "${CTEST_BINARY_DIRECTORY}" STREQUAL ""
+    AND "${CMAKE_CURRENT_BINARY_DIR}" STREQUAL "${CMAKE_CURRENT_LIST_DIR}" )
+  MESSAGE(FATAL_ERROR "
+ctest was invoked in the source directory (or test source directory) and CTEST_BINARY_DIRECTORY is not set.
+Please either call ctest from within a designated build directory, or set CTEST_BINARY_DIRECTORY accordingly.
+"
+    )
+ENDIF()
+
 #
 # Try to find the source directory and invoke
 # ./cmake/scripts/run_testsuite.cmake from this location:
-- 
2.39.5