Merge branch 'feature/test-labels' into 'master'

@timo.koch has a dire need for this on the release branch and I do not see why we shouldnt allow it.

cmake/modules/DuneTestMacros.cmake

@@ -3,6 +3,29 @@
 # Note that "the Dune way" of doing this has changed after
 # the 2.4 release. See the build system documentation for details.
 #
+# .. cmake_function:: dune_declare_test_label
+#
+#    .. cmake_brief::
+#
+#       Declare labels for :ref:`dune_add_test`.
+#
+#    .. cmake_param:: LABELS
+#       :multi:
+#
+#       The names of labels to declare.  Label names must be nonempty and
+#       consist only of alphanumeric characters plus :code:`-` and :code:`_`
+#       to make sure it is easy to construct regular expressions from them for
+#       :code:`ctest -L ${label_regex}`.
+#
+#    Labels need to be declared to ensure that the target
+#    :code:`build_${label}_tests` exists.  They will normally be declared
+#    on-demand by :ref:`dune_add_test`.  But sometimes it is useful to be able to
+#    run :code:`make build_${label}_tests` whether or not any tests with that
+#    label exists in a module.  For these cases :ref:`dune_declare_test_label` can
+#    be called explicitly.
+#
+#    The label :code:`quick` is always predeclared.
+#
 # .. cmake_function:: dune_add_test
 #
 #    .. cmake_brief::
@@ -133,6 +156,32 @@
 #       any timeout setting in ctest (see `cmake --help-property TIMEOUT`). If you
 #       specify the MPI_RANKS option, you need to specify a TIMEOUT.
 #
+#    .. cmake_param:: LABELS
+#       :multi:
+#
+#       A list of labels to add to the test.  This has two effects: it sets
+#       the LABELS property on the test so :code:`ctest -L ${label_regex}` can
+#       be used to run all tests with certain labels.  It also adds any
+#       targets created as dependencies to a custom target, so you can build
+#       all tests with a particular label by doing :code:`make
+#       build_${label}_tests` without having to build all the other tests as
+#       well.
+#
+#       The :code:`build_${label}_tests` targets are created on-demand the
+#       first time a test with that label is added.  In some situations it can
+#       depend on the values of cmake cache variables whether a test is added,
+#       and then it can happen that the :code:`build_${target}_tests` target
+#       exists only sometimes.  If your workflow relies on the existance of
+#       these targets, even if building them just returns successfully without
+#       doing anything, you can ensure they exist by calling
+#       :ref:`dune_declare_test_label` unconditionally.  The label
+#       :code:`quick` is always predeclared in this way.
+#
+#       The label names must be non-empty, and must only contain alphanumeric
+#       characters other than :code:`-` or :code:`_`.  This restriction is in
+#       place to make it easy to construct regular expressions from the label
+#       names for :code:`ctest -L ${label_regex}`.
+#
 #    This function defines the Dune way of adding a test to the testing suite.
 #    You may either add the executable yourself through :ref:`add_executable`
 #    and pass it to the :code:`TARGET` option, or you may rely on :ref:`dune_add_test`
@@ -164,6 +213,38 @@ include(CTest)
 # Introduce a target that triggers the building of all tests
 add_custom_target(build_tests)
 
+function(dune_declare_test_label)
+  include(CMakeParseArguments)
+  set(OPTIONS)
+  set(SINGLEARGS)
+  set(MULTIARGS LABELS)
+  cmake_parse_arguments(arg "${OPTIONS}" "${SINGLEARGS}" "${MULTIARGS}" ${ARGN})
+
+  if( (DEFINED arg_UNPARSED_ARGUMENTS) AND NOT ( arg_UNPARSED_ARGUMENTS STREQUAL "" ) )
+    message(FATAL_ERROR "Unhandled extra arguments given to dune_declare_test_label(): "
+      "<${arg_UNPARSED_ARGUMENTS}>")
+  endif()
+
+  foreach(label IN LISTS arg_LABELS)
+    # Make sure the label is not empty, and does not contain any funny
+    # characters, in particular regex characters
+    if(NOT (label MATCHES "[-_0-9a-zA-Z]+"))
+      message(FATAL_ERROR "Refusing to add label \"${label}\" since it is "
+        "empty or contains funny characters (characters other than "
+        "alphanumeric ones and \"-\" or \"_\"; the intent of this restriction "
+        "is to make construction of the argument to \"ctest -L\" easier")
+    endif()
+    set(target "build_${label}_tests")
+    if(NOT TARGET "${target}")
+      add_custom_target("${target}")
+    endif()
+  endforeach()
+endfunction(dune_declare_test_label)
+
+# predefine "quick" test label so build_quick_tests can be built
+# unconditionally
+dune_declare_test_label(LABELS quick)
+
 # Set the default on the variable DUNE_MAX_TEST_CORES
 if(NOT DUNE_MAX_TEST_CORES)
   set(DUNE_MAX_TEST_CORES 2)
@@ -173,7 +254,7 @@ function(dune_add_test)
   include(CMakeParseArguments)
   set(OPTIONS EXPECT_COMPILE_FAIL EXPECT_FAIL SKIP_ON_77 COMPILE_ONLY)
   set(SINGLEARGS NAME TARGET TIMEOUT)
-  set(MULTIARGS SOURCES COMPILE_DEFINITIONS COMPILE_FLAGS LINK_LIBRARIES CMD_ARGS MPI_RANKS COMMAND CMAKE_GUARD)
+  set(MULTIARGS SOURCES COMPILE_DEFINITIONS COMPILE_FLAGS LINK_LIBRARIES CMD_ARGS MPI_RANKS COMMAND CMAKE_GUARD LABELS)
   cmake_parse_arguments(ADDTEST "${OPTIONS}" "${SINGLEARGS}" "${MULTIARGS}" ${ARGN})
 
   # Check whether the parser produced any errors
@@ -269,9 +350,16 @@ function(dune_add_test)
     set_property(TARGET ${ADDTEST_TARGET} PROPERTY EXCLUDE_FROM_ALL 1)
   endif()
 
-  # Have the given target depend on build_tests in order to trigger the build correctly
+  # make sure each label exists and its name is acceptable
+  dune_declare_test_label(LABELS ${ADDTEST_LABELS})
+
+  # Have build_tests and build_${label}_tests depend on the given target in
+  # order to trigger the build correctly
   if(NOT ADDTEST_EXPECT_COMPILE_FAIL)
     add_dependencies(build_tests ${ADDTEST_TARGET})
+    foreach(label IN LISTS ADDTEST_LABELS)
+      add_dependencies(build_${label}_tests ${ADDTEST_TARGET})
+    endforeach()
   endif()
 
   # Process the EXPECT_COMPILE_FAIL option
@@ -320,6 +408,8 @@ function(dune_add_test)
       endif()
       # Skip the test if the return code is 77!
       set_tests_properties(${ACTUAL_NAME} PROPERTIES SKIP_RETURN_CODE 77)
+      # Set the labels on the test
+      set_tests_properties(${ACTUAL_NAME} PROPERTIES LABELS "${ADDTEST_LABELS}")
     endif()
   endforeach()
 endfunction()