docs/CommandGuide/lit.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 lit - LLVM Integrated Tester
   6
   7 =head1 SYNOPSIS
   8
   9 B<lit> [I<options>] [I<tests>]
  10
  11 =head1 DESCRIPTION
  12
  13 B<lit> is a portable tool for executing LLVM and Clang style test suites,
  14 summarizing their results, and providing indication of failures. B<lit> is
  15 designed to be a lightweight testing tool with as simple a user interface as
  16 possible.
  17
  18 B<lit> should be run with one or more I<tests> to run specified on the command
  19 line. Tests can be either individual test files or directories to search for
  20 tests (see L<"TEST DISCOVERY">).
  21
  22 Each specified test will be executed (potentially in parallel) and once all
  23 tests have been run B<lit> will print summary information on the number of tests
  24 which passed or failed (see L<"TEST STATUS RESULTS">). The B<lit> program will
  25 execute with a non-zero exit code if any tests fail.
  26
  27 By default B<lit> will use a succinct progress display and will only print
  28 summary information for test failures. See L<"OUTPUT OPTIONS"> for options
  29 controlling the B<lit> progress display and output.
  30
  31 B<lit> also includes a number of options for controlling how tests are exected
  32 (specific features may depend on the particular test format). See L<"EXECUTION
  33 OPTIONS"> for more information.
  34
  35 Finally, B<lit> also supports additional options for only running a subset of
  36 the options specified on the command line, see L<"SELECTION OPTIONS"> for
  37 more information.
  38
  39 =head1 GENERAL OPTIONS
  40
  41 =over
  42
  43 =item B<-h>, B<--help>
  44
  45 Show the B<lit> help message.
  46
  47 =item B<-j> I<N>, B<--threads>=I<N>
  48
  49 Run I<N> tests in parallel. By default, this is automatically chose to match the
  50 number of detected available CPUs.
  51
  52 =item B<--config-prefix>=I<NAME>
  53
  54 Search for I<NAME.cfg> and I<NAME.site.cfg> when searching for test suites,
  55 instead I<lit.cfg> and I<lit.site.cfg>.
  56
  57 =item B<--param> I<NAME>, B<--param> I<NAME>=I<VALUE>
  58
  59 Add a user defined parameter I<NAME> with the given I<VALUE> (or the empty
  60 string if not given). The meaning and use of these parameters is test suite
  61 dependent.
  62
  63 =back
  64
  65 =head1 OUTPUT OPTIONS
  66
  67 =over
  68
  69 =item B<-q>, B<--quiet>
  70
  71 Suppress any output except for test failures.
  72
  73 =item B<-s>, B<--succinct>
  74
  75 Show less output, for example don't show information on tests that pass.
  76
  77 =item B<-v>, B<--verbose>
  78
  79 Show more information on test failures, for example the entire test output
  80 instead of just the test result.
  81
  82 =item B<--no-progress-bar>
  83
  84 Do not use curses based progress bar.
  85
  86 =back
  87
  88 =head1 EXECUTION OPTIONS
  89
  90 =over
  91
  92 =item B<--path>=I<PATH>
  93
  94 Specify an addition I<PATH> to use when searching for executables in tests.
  95
  96 =item B<--vg>
  97
  98 Run individual tests under valgrind (using the memcheck tool). The
  99 I<--error-exitcode> argument for valgrind is used so that valgrind failures will
 100 cause the program to exit with a non-zero status.
 101
 102 =item B<--vg-arg>=I<ARG>
 103
 104 When I<--vg> is used, specify an additional argument to pass to valgrind itself.
 105
 106 =item B<--time-tests>
 107
 108 Track the wall time individual tests take to execute and includes the results in
 109 the summary output. This is useful for determining which tests in a test suite
 110 take the most time to execute. Note that this option is most useful with I<-j
 111 1>.
 112
 113 =back
 114
 115 =head1 SELECTION OPTIONS
 116
 117 =over
 118
 119 =item B<--max-tests>=I<N>
 120
 121 Run at most I<N> tests and then terminate.
 122
 123 =item B<--max-time>=I<N>
 124
 125 Spend at most I<N> seconds (approximately) running tests and then terminate.
 126
 127 =item B<--shuffle>
 128
 129 Run the tests in a random order.
 130
 131 =back
 132
 133 =head1 ADDITIONAL OPTIONS
 134
 135 =over
 136
 137 =item B<--debug>
 138
 139 Run B<lit> in debug mode, for debugging configuration issues and B<lit> itself.
 140
 141 =item B<--show-suites>
 142
 143 List the discovered test suites as part of the standard output.
 144
 145 =item B<--no-tcl-as-sh>
 146
 147 Run Tcl scripts internally (instead of converting to shell scripts).
 148
 149 =back
 150
 151 =head1 EXIT STATUS
 152
 153 B<lit> will exit with an exit code of 1 if there are any FAIL or XPASS
 154 results. Otherwise, it will exit with the status 0. Other exit codes used for
 155 non-test related failures (for example a user error or an internal program
 156 error).
 157
 158 =head1 TEST DISCOVERY
 159
 160 The inputs passed to B<lit> can be either individual tests, or entire
 161 directories or hierarchies of tests to run. When B<lit> starts up, the first
 162 thing it does is convert the inputs into a complete list of tests to run as part
 163 of I<test discovery>.
 164
 165 In the B<lit> model, every test must exist inside some I<test suite>. B<lit>
 166 resolves the inputs specified on the command line to test suites by searching
 167 upwards from the input path until it finds a I<lit.cfg> or I<lit.site.cfg>
 168 file. These files serve as both a marker of test suites and as configuration
 169 files which B<lit> loads in order to understand how to find and run the tests
 170 inside the test suite.
 171
 172 Once B<lit> has mapped the inputs into test suites it traverses the list of
 173 inputs adding tests for individual files and recursively searching for tests in
 174 directories.
 175
 176 This behavior makes it easy to specify a subset of tests to run, while still
 177 allowing the test suite configuration to control exactly how tests are
 178 interpreted. In addition, B<lit> always identifies tests by the test suite they
 179 are in, and their relative path inside the test suite. For appropriately
 180 configured projects, this allows B<lit> to provide convenient and flexible
 181 support for out-of-tree builds.
 182
 183 =head1 TEST STATUS RESULTS
 184
 185 Each test ultimately produces one of the following six results:
 186
 187 =over
 188
 189 =item B<PASS>
 190
 191 The test succeeded.
 192
 193 =item B<XFAIL>
 194
 195 The test failed, but that is expected. This is used for test formats which allow
 196 specifying that a test does not currently work, but wish to leave it in the test
 197 suite.
 198
 199 =item B<XPASS>
 200
 201 The test succeeded, but it was expected to fail. This is used for tests which
 202 were specified as expected to fail, but are now succeeding (generally because
 203 the feautre they test was broken and has been fixed).
 204
 205 =item B<FAIL>
 206
 207 The test failed.
 208
 209 =item B<UNRESOLVED>
 210
 211 The test result could not be determined. For example, this occurs when the test
 212 could not be run, the test itself is invalid, or the test was interrupted.
 213
 214 =item B<UNSUPPORTED>
 215
 216 The test is not supported in this environment. This is used by test formats
 217 which can report unsupported tests.
 218
 219 =back
 220
 221 Depending on the test format tests may produce additional information about
 222 their status (generally only for failures). See the L<Output|"LIT OUTPUT">
 223 section for more information.
 224
 225 =head1 SEE ALSO
 226
 227 L<valgrind(1)>
 228
 229 =head1 AUTHOR
 230
 231 Written by Daniel Dunbar and maintained by the LLVM Team (L<http://llvm.org>).
 232
 233 =cut