Help/command/ctest_start.rst

   1 ctest_start
   2 -----------
   3
   4 Starts the testing for a given model
   5
   6 ::
   7
   8   ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET])
   9
  10   ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET])
  11
  12 Starts the testing for a given model.  The command should be called
  13 after the binary directory is initialized.
  14
  15 The parameters are as follows:
  16
  17 ``<model>``
  18   Set the dashboard model. Must be one of ``Experimental``, ``Continuous``, or
  19   ``Nightly``. This parameter is required unless ``APPEND`` is specified.
  20
  21 ``<source>``
  22   Set the source directory. If not specified, the value of
  23   :variable:`CTEST_SOURCE_DIRECTORY` is used instead.
  24
  25 ``<binary>``
  26   Set the binary directory. If not specified, the value of
  27   :variable:`CTEST_BINARY_DIRECTORY` is used instead.
  28
  29 ``GROUP <group>``
  30   If ``GROUP`` is used, the submissions will go to the specified group on the
  31   CDash server. If no ``GROUP`` is specified, the name of the model is used by
  32   default.
  33
  34   .. versionchanged:: 3.16
  35     This replaces the deprecated option ``TRACK``. Despite the name
  36     change its behavior is unchanged.
  37
  38 ``APPEND``
  39   If ``APPEND`` is used, the existing ``TAG`` is used rather than creating a new
  40   one based on the current time stamp. If you use ``APPEND``, you can omit the
  41   ``<model>`` and ``GROUP <group>`` parameters, because they will be read from
  42   the generated ``TAG`` file. For example:
  43
  44   .. code-block:: cmake
  45
  46     ctest_start(Experimental GROUP GroupExperimental)
  47
  48   Later, in another ``ctest -S`` script:
  49
  50   .. code-block:: cmake
  51
  52     ctest_start(APPEND)
  53
  54   When the second script runs ``ctest_start(APPEND)``, it will read the
  55   ``Experimental`` model and ``GroupExperimental`` group from the ``TAG`` file
  56   generated by the first ``ctest_start()`` command. Please note that if you
  57   call ``ctest_start(APPEND)`` and specify a different model or group than
  58   in the first ``ctest_start()`` command, a warning will be issued, and the
  59   new model and group will be used.
  60
  61 ``QUIET``
  62   .. versionadded:: 3.3
  63
  64   If ``QUIET`` is used, CTest will suppress any non-error messages that it
  65   otherwise would have printed to the console.
  66
  67 The parameters for ``ctest_start()`` can be issued in any order, with the
  68 exception that ``<model>``, ``<source>``, and ``<binary>`` have to appear
  69 in that order with respect to each other. The following are all valid and
  70 equivalent:
  71
  72 .. code-block:: cmake
  73
  74   ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND)
  75
  76   ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary)
  77
  78   ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary)
  79
  80 However, for the sake of readability, it is recommended that you order your
  81 parameters in the order listed at the top of this page.
  82
  83 If the :variable:`CTEST_CHECKOUT_COMMAND` variable (or the
  84 :variable:`CTEST_CVS_CHECKOUT` variable) is set, its content is treated as
  85 command-line.  The command is invoked with the current working directory set
  86 to the parent of the source directory, even if the source directory already
  87 exists.  This can be used to create the source tree from a version control
  88 repository.