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 =back
  53
  54 =head1 OUTPUT OPTIONS
  55
  56 =over
  57
  58 =item B<-q>, B<--quiet>
  59
  60 Suppress any output except for test failures.
  61
  62 =item B<-s>, B<--succinct>
  63
  64 Show less output, for example don't show information on tests that pass.
  65
  66 =item B<-v>, B<--verbose>
  67
  68 Show more information on test failures, for example the entire test output
  69 instead of just the test result.
  70
  71 =item B<--no-progress-bar>
  72
  73 Do not use curses based progress bar.
  74
  75 =back
  76
  77 =head1 EXECUTION OPTIONS
  78
  79 =over
  80
  81 =item B<--path>=I<PATH>
  82
  83 Specify an addition I<PATH> to use when searching for executables in tests.
  84
  85 =item B<--vg>
  86
  87 Run individual tests under valgrind (using the memcheck tool). The
  88 I<--error-exitcode> argument for valgrind is used so that valgrind failures will
  89 cause the program to exit with a non-zero status.
  90
  91 =item B<--vg-arg>=I<ARG>
  92
  93 When I<--vg> is used, specify an additional argument to pass to valgrind itself.
  94
  95 =item B<--time-tests>
  96
  97 Track the wall time individual tests take to execute and includes the results in
  98 the summary output. This is useful for determining which tests in a test suite
  99 take the most time to execute. Note that this option is most useful with I<-j
 100 1>.
 101
 102 =back
 103
 104 =head1 SELECTION OPTIONS
 105
 106 =over
 107
 108 =item B<--max-tests>=I<N>
 109
 110 Run at most I<N> tests and then terminate.
 111
 112 =item B<--max-time>=I<N>
 113
 114 Spend at most I<N> seconds (approximately) running tests and then terminate.
 115
 116 =item B<--shuffle>
 117
 118 Run the tests in a random order.
 119
 120 =back
 121
 122 =head1 ADDITIONAL OPTIONS
 123
 124 =over
 125
 126 =item B<--debug>
 127
 128 Run B<lit> in debug mode, for debugging configuration issues and B<lit> itself.
 129
 130 =item B<--show-suites>
 131
 132 List the discovered test suites as part of the standard output.
 133
 134 =item B<--no-tcl-as-sh>
 135
 136 Run Tcl scripts internally (instead of converting to shell scripts).
 137
 138 =back
 139
 140 =head1 EXIT STATUS
 141
 142 B<lit> will exit with an exit code of 1 if there are any FAIL or XPASS
 143 results. Otherwise, it will exit with the status 0. Other exit codes used for
 144 non-test related failures (for example a user error or an internal program
 145 error).
 146
 147 =head1 TEST DISCOVERY
 148
 149 The inputs passed to B<lit> can be either individual tests, or entire
 150 directories or hierarchies of tests to run. When B<lit> starts up, the first
 151 thing it does is convert the inputs into a complete list of tests to run as part
 152 of I<test discovery>.
 153
 154 In the B<lit> model, every test must exist inside some I<test suite>. B<lit>
 155 resolves the inputs specified on the command line to test suites by searching
 156 upwards from the input path until it finds a I<lit.cfg> or I<lit.site.cfg>
 157 file. These files serve as both a marker of test suites and as configuration
 158 files which B<lit> loads in order to understand how to find and run the tests
 159 inside the test suite.
 160
 161 Once B<lit> has mapped the inputs into test suites it traverses the list of
 162 inputs adding tests for individual files and recursively searching for tests in
 163 directories.
 164
 165 This behavior makes it easy to specify a subset of tests to run, while still
 166 allowing the test suite configuration to control exactly how tests are
 167 interpreted. In addition, B<lit> always identifies tests by the test suite they
 168 are in, and their relative path inside the test suite. For appropriately
 169 configured projects, this allows B<lit> to provide convenient and flexible
 170 support for out-of-tree builds.
 171
 172 =head1 TEST STATUS RESULTS
 173
 174 Each test ultimately produces one of the following six results:
 175
 176 =over
 177
 178 =item B<PASS>
 179
 180 The test succeeded.
 181
 182 =item B<XFAIL>
 183
 184 The test failed, but that is expected. This is used for test formats which allow
 185 specifying that a test does not currently work, but wish to leave it in the test
 186 suite.
 187
 188 =item B<XPASS>
 189
 190 The test succeeded, but it was expected to fail. This is used for tests which
 191 were specified as expected to fail, but are now succeeding (generally because
 192 the feautre they test was broken and has been fixed).
 193
 194 =item B<FAIL>
 195
 196 The test failed.
 197
 198 =item B<UNRESOLVED>
 199
 200 The test result could not be determined. For example, this occurs when the test
 201 could not be run, the test itself is invalid, or the test was interrupted.
 202
 203 =item B<UNSUPPORTED>
 204
 205 The test is not supported in this environment. This is used by test formats
 206 which can report unsupported tests.
 207
 208 =back
 209
 210 Depending on the test format tests may produce additional information about
 211 their status (generally only for failures). See the L<Output|"LIT OUTPUT">
 212 section for more information.
 213
 214 =head1 SEE ALSO
 215
 216 L<valgrind(1)>
 217
 218 =head1 AUTHOR
 219
 220 Written by Daniel Dunbar and maintained by the LLVM Team (L<http://llvm.org>).
 221
 222 =cut