1 /*============================================================================
2 CMake - Cross Platform Makefile Generator
3 Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
5 Distributed under the OSI-approved BSD License (the "License");
6 see accompanying file Copyright.txt for details.
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 ============================================================================*/
13 #include "cmSystemTools.h"
15 // Need these for documentation support.
17 #include "cmDocumentation.h"
19 #include "CTest/cmCTestScriptHandler.h"
20 #include "CTest/cmCTestLaunch.h"
22 //----------------------------------------------------------------------------
23 static const char * cmDocumentationName[][3] =
26 " ctest - Testing driver provided by CMake.", 0},
30 //----------------------------------------------------------------------------
31 static const char * cmDocumentationUsage[][3] =
34 " ctest [options]", 0},
38 //----------------------------------------------------------------------------
39 static const char * cmDocumentationDescription[][3] =
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},
49 //----------------------------------------------------------------------------
50 static const char * cmDocumentationOptions[][3] =
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 "
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 "
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 "
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 "
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 "
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 "
127 {"-S <script>, --script <script>", "Execute a dashboard for a "
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 "
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 "
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 "
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"
203 {"--test-command", "The test to run with the --build-and-test option.", ""
205 {"--test-timeout", "The time limit in seconds, internal use only.", ""
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 "
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." },
257 //----------------------------------------------------------------------------
258 static const char * cmDocumentationSeeAlso[][3] =
265 // this is a test driver program for cmCTest.
266 int main (int argc, char *argv[])
268 cmSystemTools::DoNotInheritStdPipes();
269 cmSystemTools::EnableMSVCDebugHook();
270 cmSystemTools::FindExecutableDirectory(argv[0]);
272 // Dispatch 'ctest --launch' mode directly.
273 if(argc >= 2 && strcmp(argv[1], "--launch") == 0)
275 return cmCTestLaunch::Main(argc, argv);
280 if ( cmSystemTools::GetCurrentWorkingDirectory().size() == 0 )
282 cmCTestLog(&inst, ERROR_MESSAGE,
283 "Current working directory cannot be established." << std::endl);
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")))
295 cmCTestLog(&inst, ERROR_MESSAGE, "*********************************"
297 << "No test configuration file found!" << std::endl
298 << "*********************************" << std::endl);
301 doc.addCTestStandardDocSections();
302 if(doc.CheckOptions(argc, argv))
304 // Construct and print requested documentation.
305 std::vector<cmDocumentationEntry> commands;
306 cmCTestScriptHandler* ch =
307 static_cast<cmCTestScriptHandler*>(inst.GetHandler("script"));
309 ch->GetCommandDocumentation(commands);
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);
322 return doc.PrintRequestedDocumentation(std::cout)? 0:1;
323 #define cout no_cout_use_cmCTestLog
328 std::string comspec = "cmw9xcom.exe";
329 cmSystemTools::SetWindows9xComspecSubstitute(comspec.c_str());
331 // copy the args to a vector
332 std::vector<std::string> args;
333 for(int i =0; i < argc; ++i)
335 args.push_back(argv[i]);
339 int res = inst.Run(args,&output);
340 cmCTestLog(&inst, OUTPUT, output);