]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
Finish documentation
authormaier <maier@0785d39b-7218-0410-832d-ea1e28bc413d>
Sun, 13 Oct 2013 16:21:18 +0000 (16:21 +0000)
committermaier <maier@0785d39b-7218-0410-832d-ea1e28bc413d>
Sun, 13 Oct 2013 16:21:18 +0000 (16:21 +0000)
git-svn-id: https://svn.dealii.org/branches/branch_port_the_testsuite@31215 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/cmake/scripts/run_buildtest.cmake [moved from tests/run_buildtests.cmake with 100% similarity]
deal.II/cmake/scripts/run_testsuite.cmake
deal.II/doc/developers/testsuite.html
tests/run_buildtest.cmake [new file with mode: 0644]
tests/run_testsuite.cmake

index 89dae024aa55f311a63fecaa3b916645eb9458aa..6e496b0b556f9da83aebcfbf5fbe7af1c908beff 100644 (file)
@@ -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... )
index 5c22d9454c8ae56f66ee5d597e4a40fe50198192..754e765dc37eea62c1855f1bea79aa117090b439 100644 (file)
@@ -79,6 +79,7 @@
     <p>
       If you're impatient, use the following commands:
       <pre>
+
     $ mkdir new_directory
     $ cd new_directory
     $ svn checkout https://svn.dealii.org/trunk .
       and modify it to where it does what we'd like to test. Alternatively,
       you can also start from a template like this:
     <pre>
+
 // ---------------------------------------------------------------------
 // $Id$
 //
@@ -661,9 +663,82 @@ int main ()
     <a name="submit"></a>
     <h2>Submitting test results</h2>
 
-    <p class="todo">
-      Explain how to use <code>run_testsuite.cmake</code> in all imaginable
-      ways...
+    <p>
+      To submit test results to our <a
+        href="http://cdash.kyomu.43-1.org/index.php?project=deal.II">CDash</a>
+      instance just invoke ctest within a build directory (or designated
+      build directory) with the <code>-S</code> option pointing to the
+      <code>run_testsuite.cmake</code> script: <pre>
+
+      $ ctest [...] -V -S ../tests/run_testsuite.cmake
+      </pre>
+      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 <code>ctest</code> as explained above.
+    </p>
+
+    <p>
+      <b>Note:</b> The default output in script mode is very minimal.
+      Therefore, it is recommended to specify <code>-V</code> which will
+      give the same level of verbosity as the non-script mode.
+    </p>
+
+    <p>
+      <b>Note:</b> The following variables can be set to via
+      <pre>
+
+    ctest -D&lt;variable&gt;=&lt;value&gt; [...]
+      </pre>
+      to control the behaviour of the <code>run_testsuite.cmake</code>
+      script:
+      <pre>
+
+    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.
+      </pre>
+      Furthermore, the variables described <a href="#setupconfigure">above</a> can also be
+      set and will be handed automatically down to <code>cmake</code>.
     </p>
 
 
@@ -674,70 +749,43 @@ int main ()
     <p>
       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 <a
-      href="http://www.dealii.org/testsuite.html">online</a>.<p>
+      different configuration options. Results are collected in the "Build
+      Tests" track in <a
+      href="http://cdash.kyomu.43-1.org/index.php?project=deal.II">CDash</a>.<p>
 
       <p>Running the build test suite is simple and we encourage deal.II
       users with configurations not found on the <a
       href="http://www.dealii.org/testsuite.html">test suite page</a> to
       participate. Assuming you checked out deal.II into the directory
-      <code>dealtest</code>, running it is as simple as:
+      <code>deal.II</code>, running it is as simple as:
       <pre>
 
-    cd dealtest
-    svn update
-    ./contrib/utilities/build_test
-    mail build-tests@dealii.org &lt; *.log
-  ( rm *.log )
+    cd deal.II
+    mkdir build
+    cd build
+    ctest -j4 -S ../cmake/scripts/run_buildtest.cmake
       </pre>
     </p>
 
     <p>
-      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
+      <code>build</code>, 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.
     </p>
 
     <p>
-      The <code>build_test</code> script supports the following options:
+      <b>Note:</b> 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 <a href="../users/Config.sample">configuration file</a>
+      to preseed the cache as explained <a href="#submit">above</a>:
       <pre>
 
-    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.<unix time>.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"
-      </pre>
-      An example configuration file can be found <a
-      href="../users/Config.sample">here</a>. Options can be passed either via
-    environment variables
-      <pre>
-
-    export CONFIGFILE=MyConfiguration.conf
-    ./contrib/utilities/build_test
-      </pre>
-      or directly on the command line:
-      <pre>
-
-    ./contrib/utilities/build_test CONFIGFILE=myConfiguration.conf
+    $ ctest -DCONFIG_FILE="[...]/Config.sample" [...]
       </pre>
     </p>
 
-    <p>
-      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).
-    </p>
 
 
     <a name="dedicatedbuilds"></a>
diff --git a/tests/run_buildtest.cmake b/tests/run_buildtest.cmake
new file mode 100644 (file)
index 0000000..98014f1
--- /dev/null
@@ -0,0 +1,2 @@
+SET(TRACK "Build Tests")
+INCLUDE(${CMAKE_CURRENT_LIST_DIR}/run_testsuite.cmake)
index 51f970e900865f1ff8bf914deb8a98131aa9dcc0..6723f32917838d145a55b25157f8cc41fe3cd7cf 100644 (file)
 ##
 ## ---------------------------------------------------------------------
 
+#
+# 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:

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.