Source/ctest.cxx

   1 /*============================================================================
   2   CMake - Cross Platform Makefile Generator
   3   Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
   4
   5   Distributed under the OSI-approved BSD License (the "License");
   6   see accompanying file Copyright.txt for details.
   7
   8   This software is distributed WITHOUT ANY WARRANTY; without even the
   9   implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  10   See the License for more information.
  11 ============================================================================*/
  12 #include "cmCTest.h"
  13 #include "cmSystemTools.h"
  14
  15 // Need these for documentation support.
  16 #include "cmake.h"
  17 #include "cmDocumentation.h"
  18
  19 #include "CTest/cmCTestScriptHandler.h"
  20 #include "CTest/cmCTestLaunch.h"
  21
  22 //----------------------------------------------------------------------------
  23 static const char * cmDocumentationName[][3] =
  24 {
  25   {0,
  26    "  ctest - Testing driver provided by CMake.", 0},
  27   {0,0,0}
  28 };
  29
  30 //----------------------------------------------------------------------------
  31 static const char * cmDocumentationUsage[][3] =
  32 {
  33   {0,
  34    "  ctest [options]", 0},
  35   {0,0,0}
  36 };
  37
  38 //----------------------------------------------------------------------------
  39 static const char * cmDocumentationDescription[][3] =
  40 {
  41   {0,
  42    "The \"ctest\" executable is the CMake test driver program.  "
  43    "CMake-generated build trees created for projects that use "
  44    "the ENABLE_TESTING and ADD_TEST commands have testing support.  "
  45    "This program will run the tests and report results.", 0},
  46   {0,0,0}
  47 };
  48
  49 //----------------------------------------------------------------------------
  50 static const char * cmDocumentationOptions[][3] =
  51 {
  52   {"-C <cfg>, --build-config <cfg>", "Choose configuration to test.",
  53    "Some CMake-generated build trees can have multiple build configurations "
  54    "in the same tree.  This option can be used to specify which one should "
  55    "be tested.  Example configurations are \"Debug\" and \"Release\"."},
  56   {"-V,--verbose", "Enable verbose output from tests.",
  57    "Test output is normally suppressed and only summary information is "
  58    "displayed.  This option will show all test output."},
  59   {"-VV,--extra-verbose", "Enable more verbose output from tests.",
  60    "Test output is normally suppressed and only summary information is "
  61    "displayed.  This option will show even more test output."},
  62   {"--debug", "Displaying more verbose internals of CTest.",
  63     "This feature will result in a large number of output that is mostly "
  64     "useful for debugging dashboard problems."},
  65   {"--output-on-failure", "Output anything outputted by the test program "
  66    "if the test should fail.  This option can also be enabled by setting "
  67    "the environment variable CTEST_OUTPUT_ON_FAILURE"},
  68   {"-F", "Enable failover.", "This option allows ctest to resume a test "
  69    "set execution that was previously interrupted.  If no interruption "
  70    "occurred, the -F option will have no effect."},
  71   {"-j <jobs>, --parallel <jobs>", "Run the tests in parallel using the"
  72    "given number of jobs.",
  73    "This option tells ctest to run the tests in parallel using given "
  74    "number of jobs.  This option can also be set by setting "
  75    "the environment variable CTEST_PARALLEL_LEVEL."},
  76   {"-Q,--quiet", "Make ctest quiet.",
  77     "This option will suppress all the output. The output log file will "
  78     "still be generated if the --output-log is specified. Options such "
  79     "as --verbose, --extra-verbose, and --debug are ignored if --quiet is "
  80     "specified."},
  81   {"-O <file>, --output-log <file>", "Output to log file",
  82    "This option tells ctest to write all its output to a log file."},
  83   {"-N,--show-only", "Disable actual execution of tests.",
  84    "This option tells ctest to list the tests that would be run but not "
  85    "actually run them.  Useful in conjunction with the -R and -E options."},
  86   {"-L <regex>, --label-regex <regex>", "Run tests with labels matching "
  87    "regular expression.",
  88    "This option tells ctest to run only the tests whose labels match the "
  89    "given regular expression."},
  90   {"-R <regex>, --tests-regex <regex>", "Run tests matching regular "
  91    "expression.",
  92    "This option tells ctest to run only the tests whose names match the "
  93    "given regular expression."},
  94   {"-E <regex>, --exclude-regex <regex>", "Exclude tests matching regular "
  95    "expression.",
  96    "This option tells ctest to NOT run the tests whose names match the "
  97    "given regular expression."},
  98   {"-LE <regex>, --label-exclude <regex>", "Exclude tests with labels "
  99    "matching regular expression.",
 100    "This option tells ctest to NOT run the tests whose labels match the "
 101    "given regular expression."},
 102   {"-D <dashboard>, --dashboard <dashboard>", "Execute dashboard test",
 103    "This option tells ctest to act as a Dart client and perform "
 104    "a dashboard test. All tests are <Mode><Test>, where Mode can be "
 105    "Experimental, Nightly, and Continuous, and Test can be Start, Update, "
 106    "Configure, Build, Test, Coverage, and Submit."},
 107   {"-D <var>:<type>=<value>", "Define a variable for script mode",
 108    "Pass in variable values on the command line. Use in "
 109    "conjunction with -S to pass variable values to a dashboard script. "
 110    "Parsing -D arguments as variable values is only attempted if "
 111    "the value following -D does not match any of the known dashboard "
 112    "types."},
 113   {"-M <model>, --test-model <model>", "Sets the model for a dashboard",
 114    "This option tells ctest to act as a Dart client "
 115    "where the TestModel can be Experimental, "
 116    "Nightly, and Continuous. Combining -M and -T is similar to -D"},
 117   {"-T <action>, --test-action <action>", "Sets the dashboard action to "
 118    "perform",
 119    "This option tells ctest to act as a Dart client "
 120    "and perform some action such as start, build, test etc. "
 121    "Combining -M and -T is similar to -D"},
 122   {"--track <track>", "Specify the track to submit dashboard to",
 123    "Submit dashboard to specified track instead of default one. By "
 124    "default, the dashboard is submitted to Nightly, Experimental, or "
 125    "Continuous track, but by specifying this option, the track can be "
 126    "arbitrary."},
 127   {"-S <script>, --script <script>", "Execute a dashboard for a "
 128    "configuration",
 129    "This option tells ctest to load in a configuration script which sets "
 130    "a number of parameters such as the binary and source directories. Then "
 131    "ctest will do what is required to create and run a dashboard. This "
 132    "option basically sets up a dashboard and then runs ctest -D with the "
 133    "appropriate options."},
 134   {"-SP <script>, --script-new-process <script>", "Execute a dashboard for a "
 135    "configuration",
 136    "This option does the same operations as -S but it will do them in a "
 137    "separate process. This is primarily useful in cases where the script "
 138    "may modify the environment and you do not want the modified environment "
 139    "to impact other -S scripts."},
 140   {"-A <file>, --add-notes <file>", "Add a notes file with submission",
 141    "This option tells ctest to include a notes file when submitting "
 142    "dashboard. "},
 143   {"-I [Start,End,Stride,test#,test#|Test file], --tests-information",
 144    "Run a specific number of tests by number.",
 145    "This option causes ctest to run tests starting at number Start, ending "
 146    "at number End, and incrementing by Stride. Any additional numbers after "
 147    "Stride are considered individual test numbers.  Start, End,or stride "
 148    "can be empty.  Optionally a file can be given that contains the same "
 149    "syntax as the command line."},
 150   {"-U, --union", "Take the Union of -I and -R",
 151    "When both -R and -I are specified by default the intersection of "
 152    "tests are run. By specifying -U the union of tests is run instead."},
 153   {"--max-width <width>", "Set the max width for a test name to output",
 154    "Set the maximum width for each test name to show in the output.  This "
 155    "allows the user to widen the output to avoid clipping the test name which "
 156    "can be very annoying."},
 157   {"--interactive-debug-mode [0|1]", "Set the interactive mode to 0 or 1.",
 158    "This option causes ctest to run tests in either an interactive mode or "
 159    "a non-interactive mode. On Windows this means that in non-interactive "
 160    "mode, all system debug pop up windows are blocked. In dashboard mode "
 161    "(Experimental, Nightly, Continuous), the default is non-interactive.  "
 162    "When just running tests not for a dashboard the default is to allow "
 163    "popups and interactive "
 164    "debugging."},
 165   {"--no-label-summary", "Disable timing summary information for labels.",
 166    "This option tells ctest not to print summary information for each label "
 167    "associated with the tests run. If there are no labels on the "
 168    "tests, nothing extra is printed."},
 169   {"--build-and-test", "Configure, build and run a test.",
 170    "This option tells ctest to configure (i.e. run cmake on), build, and or "
 171    "execute a test. The configure and test steps are optional. The arguments "
 172    "to this command line are the source and binary directories. By default "
 173    "this will run CMake on the Source/Bin directories specified unless "
 174    "--build-nocmake is specified. Both --build-makeprogram and "
 175    "--build-generator MUST be provided to use --build-and-test. If "
 176    "--test-command is specified then that will be run after the build is "
 177    "complete. Other options that affect this mode are --build-target "
 178    "--build-nocmake, --build-run-dir, "
 179    "--build-two-config, --build-exe-dir, --build-project,"
 180    "--build-noclean, --build-options"},
 181   {"--build-target", "Specify a specific target to build.",
 182    "This option goes with the --build-and-test option, if left out the all "
 183    "target is built." },
 184   {"--build-nocmake", "Run the build without running cmake first.",
 185    "Skip the cmake step." },
 186   {"--build-run-dir", "Specify directory to run programs from.",
 187    "Directory where programs will be after it has been compiled." },
 188   {"--build-two-config", "Run CMake twice", "" },
 189   {"--build-exe-dir", "Specify the directory for the executable.", "" },
 190   {"--build-generator", "Specify the generator to use.", "" },
 191   {"--build-generator-toolset", "Specify the generator-specific toolset.",""},
 192   {"--build-project", "Specify the name of the project to build.", "" },
 193   {"--build-makeprogram", "Specify the make program to use.", "" },
 194   {"--build-noclean", "Skip the make clean step.", "" },
 195   {"--build-config-sample",
 196    "A sample executable to use to determine the configuration",
 197    "A sample executable to use to determine the configuration that "
 198    "should be used. e.g. Debug/Release/etc" },
 199   {"--build-options", "Add extra options to the build step.",
 200    "This option must be the last option with the exception of --test-command"
 201   },
 202
 203   {"--test-command", "The test to run with the --build-and-test option.", ""
 204   },
 205   {"--test-timeout", "The time limit in seconds, internal use only.", ""
 206   },
 207   {"--tomorrow-tag", "Nightly or experimental starts with next day tag.",
 208    "This is useful if the build will not finish in one day." },
 209   {"--ctest-config", "The configuration file used to initialize CTest state "
 210   "when submitting dashboards.",
 211    "This option tells CTest to use different initialization file instead of "
 212    "CTestConfiguration.tcl. This way multiple initialization files can be "
 213    "used for example to submit to multiple dashboards." },
 214   {"--overwrite", "Overwrite CTest configuration option.",
 215    "By default ctest uses configuration options from configuration file. "
 216    "This option will overwrite the configuration option." },
 217   {"--extra-submit <file>[;<file>]", "Submit extra files to the dashboard.",
 218    "This option will submit extra files to the dashboard." },
 219   {"--force-new-ctest-process", "Run child CTest instances as new processes",
 220    "By default CTest will run child CTest instances within the same process. "
 221    "If this behavior is not desired, this argument will enforce new "
 222    "processes for child CTest processes." },
 223   {"--schedule-random", "Use a random order for scheduling tests",
 224    "This option will run the tests in a random order. It is commonly used to "
 225    "detect implicit dependencies in a test suite." },
 226   {"--submit-index", "Submit individual dashboard tests with specific index",
 227    "This option allows performing the same CTest action (such as test) "
 228    "multiple times and submit all stages to the same dashboard (Dart2 "
 229    "required). Each execution requires different index." },
 230   {"--timeout <seconds>", "Set a global timeout on all tests.",
 231    "This option will set a global timeout on all tests that do not already "
 232    "have a timeout set on them."},
 233   {"--stop-time <time>", "Set a time at which all tests should stop running.",
 234    "Set a real time of day at which all tests should timeout. Example: "
 235    "7:00:00 -0400. Any time format understood by the curl date parser is "
 236    "accepted. Local time is assumed if no timezone is specified."},
 237   {"--http1.0", "Submit using HTTP 1.0.",
 238   "This option will force CTest to use HTTP 1.0 to submit files to the "
 239   "dashboard, instead of HTTP 1.1."},
 240   {"--no-compress-output", "Do not compress test output when submitting.",
 241    "This flag will turn off automatic compression of test output.  Use this "
 242    "to maintain compatibility with an older version of CDash which doesn't "
 243    "support compressed test output."},
 244   {"--print-labels", "Print all available test labels.",
 245    "This option will not run any tests, it will simply print the list of "
 246    "all labels associated with the test set."},
 247   {"--help-command <cmd> [<file>]", "Show help for a single command and exit.",
 248    "Prints the help for the command to stdout or to the specified file." },
 249   {"--help-command-list [<file>]", "List available commands and exit.",
 250    "Prints the list of all available listfile commands to stdout or the "
 251    "specified file." },
 252   {"--help-commands [<file>]", "Print help for all commands and exit.",
 253    "Prints the help for all commands to stdout or to the specified file." },
 254   {0,0,0}
 255 };
 256
 257 //----------------------------------------------------------------------------
 258 static const char * cmDocumentationSeeAlso[][3] =
 259 {
 260   {0, "cmake", 0},
 261   {0, "ccmake", 0},
 262   {0, 0, 0}
 263 };
 264
 265 // this is a test driver program for cmCTest.
 266 int main (int argc, char *argv[])
 267 {
 268   cmSystemTools::DoNotInheritStdPipes();
 269   cmSystemTools::EnableMSVCDebugHook();
 270   cmSystemTools::FindExecutableDirectory(argv[0]);
 271
 272   // Dispatch 'ctest --launch' mode directly.
 273   if(argc >= 2 && strcmp(argv[1], "--launch") == 0)
 274     {
 275     return cmCTestLaunch::Main(argc, argv);
 276     }
 277
 278   cmCTest inst;
 279
 280   if ( cmSystemTools::GetCurrentWorkingDirectory().size() == 0 )
 281     {
 282     cmCTestLog(&inst, ERROR_MESSAGE,
 283       "Current working directory cannot be established." << std::endl);
 284     return 1;
 285     }
 286
 287   // If there is a testing input file, check for documentation options
 288   // only if there are actually arguments.  We want running without
 289   // arguments to run tests.
 290   if(argc > 1 || !(cmSystemTools::FileExists("CTestTestfile.cmake") ||
 291                    cmSystemTools::FileExists("DartTestfile.txt")))
 292     {
 293     if(argc == 1)
 294       {
 295       cmCTestLog(&inst, ERROR_MESSAGE, "*********************************"
 296         << std::endl
 297         << "No test configuration file found!" << std::endl
 298         << "*********************************" << std::endl);
 299       }
 300     cmDocumentation doc;
 301     doc.addCTestStandardDocSections();
 302     if(doc.CheckOptions(argc, argv))
 303       {
 304       // Construct and print requested documentation.
 305       std::vector<cmDocumentationEntry> commands;
 306       cmCTestScriptHandler* ch =
 307                  static_cast<cmCTestScriptHandler*>(inst.GetHandler("script"));
 308       ch->CreateCMake();
 309       ch->GetCommandDocumentation(commands);
 310
 311       doc.SetShowGenerators(false);
 312       doc.SetName("ctest");
 313       doc.SetSection("Name",cmDocumentationName);
 314       doc.SetSection("Usage",cmDocumentationUsage);
 315       doc.SetSection("Description",cmDocumentationDescription);
 316       doc.PrependSection("Options",cmDocumentationOptions);
 317       doc.SetSection("Commands",commands);
 318       doc.SetSeeAlsoList(cmDocumentationSeeAlso);
 319 #ifdef cout
 320 #  undef cout
 321 #endif
 322       return doc.PrintRequestedDocumentation(std::cout)? 0:1;
 323 #define cout no_cout_use_cmCTestLog
 324       }
 325     }
 326
 327 #ifdef _WIN32
 328   std::string comspec = "cmw9xcom.exe";
 329   cmSystemTools::SetWindows9xComspecSubstitute(comspec.c_str());
 330 #endif
 331   // copy the args to a vector
 332   std::vector<std::string> args;
 333   for(int i =0; i < argc; ++i)
 334     {
 335     args.push_back(argv[i]);
 336     }
 337   // run ctest
 338   std::string output;
 339   int res = inst.Run(args,&output);
 340   cmCTestLog(&inst, OUTPUT, output);
 341
 342   return res;
 343 }
 344