docs/TestingGuide.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2                       "http://www.w3.org/TR/html4/strict.dtd">
   3 <html>
   4 <head>
   5   <title>LLVM Test Suite Guide</title>
   6   <link rel="stylesheet" href="llvm.css" type="text/css">
   7 </head>
   8 <body>
   9
  10 <div class="doc_title">
  11   LLVM Test Suite Guide
  12 </div>
  13
  14 <ol>
  15 <li><a href="#overview">Overview</a></li>
  16 <li><a href="#Requirements">Requirements</a></li>
  17 <li><a href="#quick">Quick Start</a></li>
  18 <li><a href="#org">LLVM Test Suite Organization</a>
  19 <ul>
  20   <li><a href="#codefragments">Code Fragments</a></li>
  21   <li><a href="#wholeprograms">Whole Programs</a></li>
  22 </ul></li>
  23 <li><a href="#tree">LLVM Test Suite Tree</a></li>
  24 <li><a href="#qmstructure">QMTest Structure</a></li>
  25 <li><a href="#progstructure">Programs Structure</a></li>
  26 <li><a href="#run">Running the LLVM Tests</a></li>
  27 </ol>
  28
  29 <div class="doc_author">
  30   <p>Written by John T. Criswell</p>
  31 </div>
  32
  33 <!--===============================================================-->
  34 <div class="doc_section"><a name="overview">Overview</a></div>
  35 <!--===============================================================-->
  36
  37 <div class="doc_text">
  38
  39 <p>This document is the reference manual for the LLVM test suite.  It documents
  40 the structure of the LLVM test suite, the tools needed to use it, and how to add
  41 and run tests.</p>
  42
  43 </div>
  44
  45 <!--===============================================================-->
  46 <div class="doc_section"><a name="Requirements">Requirements</a></div>
  47 <!--===============================================================-->
  48
  49 <div class="doc_text">
  50
  51 <p>In order to use the LLVM test suite, you will need all of the software
  52 required to build LLVM, plus the following:</p>
  53
  54 <dl>
  55   <dt><a href="http://www.qmtest.com">QMTest</A></dt>
  56   <dd>The LLVM test suite uses QMTest to organize and run tests. <b>Note:
  57   you will need <a href="http://llvm.cs.uiuc.edu/qm-2.0.3.tar.gz">QMTest
  58   2.0.3 (source tar.gz file)</a> to be successful. The tests do not run with
  59   any other version.</b></dd>
  60
  61   <dt><a href="http://www.python.org">Python</A></dt>
  62   <dd>You will need a Python interpreter that works with QMTest. Python will
  63   need zlib and SAX support enabled.</dd>
  64 </dl>
  65
  66 </div>
  67
  68 <!--===============================================================-->
  69 <div class="doc_section"><a name="quick">Quick Start</a></div>
  70 <!--===============================================================-->
  71
  72 <div class="doc_text">
  73
  74 <p> The tests are located in the LLVM source tree under the directory
  75 <tt>llvm/test</tt>. To run all of the tests in LLVM, use the Master Makefile in
  76 that directory:</p>
  77
  78 <pre>
  79  % gmake -C llvm/test
  80 </pre>
  81
  82 <p>To run only the code fragment tests (i.e. those that do basic testing of
  83 LLVM), run the tests organized by QMTest:</p>
  84
  85 <pre>
  86  % gmake -C llvm/test qmtest
  87 </pre>
  88
  89 <p>To run only the tests that compile and execute whole programs, run the
  90 Programs tests:</p>
  91
  92 <pre>
  93  % gmake -C llvm/test/Programs
  94 </pre>
  95
  96 </div>
  97
  98 <!--===============================================================-->
  99 <div class="doc_section"><a name="org">LLVM Test Suite Organization</a></div>
 100 <!--===============================================================-->
 101
 102 <div class="doc_text">
 103
 104 <p>The LLVM test suite contains two major categories of tests: code
 105 fragments and whole programs.</p>
 106
 107 </div>
 108
 109 <div class="doc_subsection"><a name="codefragments">Code Fragments</a>
 110 </div>
 111
 112 <div class="doc_text">
 113
 114 <p>Code fragments are small pieces of code that test a specific feature of LLVM
 115 or trigger a specific bug in LLVM.  They are usually written in LLVM assembly
 116 language, but can be written in other languages if the test targets a particular
 117 language front end.</p>
 118
 119 <p>Code fragments are not complete programs, and they are never executed to
 120 determine correct behavior.</p>
 121
 122 <p>The tests in the Features and Regression directories contain code
 123 fragments.</p>
 124
 125 </div>
 126
 127 <div class="doc_subsection"><a name="wholeprograms">Whole Programs</a></div>
 128
 129 <div class="doc_text">
 130
 131 <p>Whole Programs are pieces of code which can be compiled and linked into a
 132 stand-alone program that can be executed.  These programs are generally written
 133 in high level languages such as C or C++, but sometimes they are written
 134 straight in LLVM assembly.</p>
 135
 136 <p>These programs are compiled and then executed using several different
 137 methods (native compiler, LLVM C backend, LLVM JIT, LLVM native code generation,
 138 etc).  The output of these programs is compared to ensure that LLVM is compiling
 139 the program correctly.</p>
 140
 141 <p>In addition to compiling and executing programs, whole program tests serve as
 142 a way of benchmarking LLVM performance, both in terms of the efficiency of the
 143 programs generated as well as the speed with which LLVM compiles, optimizes, and
 144 generates code.</p>
 145
 146 <p>The Programs directory contains all tests which compile and benchmark whole
 147 programs.</p>
 148
 149 </div>
 150
 151 <!--===============================================================-->
 152 <div class="doc_section"><a name="tree">LLVM Test Suite Tree</a></div>
 153 <!--===============================================================-->
 154
 155 <div class="doc_text">
 156
 157 <p>Each type of test in the LLVM test suite has its own directory. The major
 158 subtrees of the test suite directory tree are as follows:</p>
 159
 160 <ul>
 161   <li>Features
 162     <p>This directory contains sample codes that test various features of the
 163     LLVM language.  These pieces of sample code are run through various
 164     assembler, disassembler, and optimizer passes.</p>
 165
 166   <li>Regression
 167     <p>This directory contains regression tests for LLVM.  When a bug is found
 168     in LLVM, a regression test containing just enough code to reproduce the
 169     problem should be written and placed somewhere underneath this directory.
 170     In most cases, this will be a small piece of LLVM assembly language code,
 171     often distilled from an actual application or benchmark.</p>
 172
 173   <li>Programs
 174     <p>The Programs directory contains programs that can be compiled with LLVM
 175     and executed.  These programs are compiled using the native compiler and
 176     various LLVM backends.  The output from the program compiled with the native
 177     compiler is assumed correct; the results from the other programs are
 178     compared to the native program output and pass if they match.  </p>
 179
 180     <p> In addition for testing correctness, the Programs directory also
 181     performs timing tests of various LLVM optimizations.  It also records
 182     compilation times for the compilers and the JIT.  This information can be
 183     used to compare the effectiveness of LLVM's optimizations and code
 184     generation.</p>
 185
 186     <p>The Programs directory is subdivided into several smaller subdirectories:
 187     </p>
 188
 189     <ul>
 190       <li>Programs/SingleSource
 191         <p>The SingleSource directory contains test programs that are only a
 192         single source file in size.  These are usually small benchmark programs
 193         or small programs that calculate a particular value.  Several such
 194         programs are grouped together in each directory.</p></li>
 195
 196       <li>Programs/MultiSource
 197         <p>The MultiSource directory contains subdirectories which contain
 198         entire programs with multiple source files.  Large benchmarks and whole
 199         applications go here.</p></li>
 200
 201       <li>Programs/External
 202         <p>The External directory contains Makefiles for building code that is
 203         external to (i.e. not distributed with) LLVM.  The most prominent member
 204         of this directory is the SPEC 2000 benchmark suite.  The presence and
 205         location of these external programs is configured by the LLVM
 206         <tt>configure</tt> script.</p></li>
 207
 208     </ul></li>
 209
 210   <li>QMTest
 211     <p>This directory contains the QMTest information files.  Inside this
 212     directory are QMTest administration files and the Python code that
 213     implements the LLVM test and database classes.</p>
 214
 215 </ul>
 216
 217 </div>
 218
 219 <!--===============================================================-->
 220 <div class="doc_section"><a name="qmstructure">QMTest Structure</a></div>
 221 <!--===============================================================-->
 222
 223 <div class="doc_text">
 224
 225 <p>The LLVM test suite is partially driven by QMTest and partially
 226 driven by GNU Make.  Specifically, the Features and Regression tests
 227 are all driven by QMTest.  The Programs directory is currently
 228 driven by a set of Makefiles.</p>
 229
 230 <p>The QMTest system needs to have several pieces of information
 231 available; these pieces of configuration information are known
 232 collectively as the "context" in QMTest parlance.  Since the context
 233 for LLVM is relatively large, the master Makefile in llvm/test
 234 sets it for you.</p>
 235
 236 <p>The LLVM database class makes the subdirectories of llvm/test a
 237 QMTest test database.  For each directory that contains tests driven by
 238 QMTest, it knows what type of test the source file is and how to run it.</p>
 239
 240 <p>Hence, the QMTest namespace is essentially what you see in the
 241 Feature and Regression directories, but there is some magic that
 242 the database class performs (as described below).</p>
 243
 244 <p>The QMTest namespace is currently composed of the following tests and test
 245 suites:</p>
 246
 247 <ul>
 248   <li>Feature
 249               <p>
 250   These are the feature tests found in the Feature directory.
 251   They are broken up into the following categories:
 252               </p>
 253   <ul>
 254     <li>ad
 255       <p>Assembler/Disassembler tests.  These tests verify that a piece of LLVM
 256       assembly language can be assembled into bytecode and then disassembled
 257       into the original assembly language code.  It does this several times to
 258       ensure that assembled output can be disassembled and disassembler output
 259       can be assembled.  It also verifies that the give assembly language file
 260       can be assembled correctly.</p></li>
 261
 262     <li>opt
 263       <p>Optimizer tests.  These tests verify that two of the optimizer passes
 264       completely optimize a program (i.e.  after a single pass, they cannot
 265       optimize a program any further).</p></li>
 266
 267     <li>mc
 268       <p> Machine code tests.  These tests verify that the LLVM assembly
 269       language file can be translated into native assembly code.</p></li>
 270
 271     <li>cc
 272       <p>C code tests.  These tests verify that the specified LLVM assembly
 273       code can be converted into C source code using the C backend.</p></li>
 274   </ul>
 275
 276   <p>The LLVM database class looks at every file in the Feature directory and
 277   creates a fake test hierarchy containing
 278   <tt>Feature.&lt;testtype&gt;.&lt;testname&gt;</tt>.  So, if you add an LLVM
 279   assembly language file to the Feature directory, it actually creates 5 new
 280   tests: assembler/disassembler, assembler, optimizer, machine code, and C code.
 281   </p>
 282
 283   <li>Regression
 284     <p>These are the regression tests.  There is one suite for each
 285     subdirectory of the Regression directory.  If you add a new subdirectory
 286     there, you will need to modify, at least, the <tt>RegressionMap</tt>
 287     variable in <tt>QMTest/llvmdb.py</tt> so that QMTest knows how to run the
 288     tests in the new subdirectory.</p>
 289
 290 </ul>
 291
 292 </div>
 293
 294 <!--===============================================================-->
 295 <div class="doc_section"><a name="progstructure">Programs Structure</a></div>
 296 <!--===============================================================-->
 297
 298 <div class="doc_text">
 299
 300 <p>As mentioned previously, the Programs tree in llvm/test provides three types
 301 of tests: MultiSource, SingleSource, and External.  Each tree is then subdivided
 302 into several categories, including applications, benchmarks, regression tests,
 303 code that is strange grammatically, etc.  These organizations should be
 304 relatively self explanatory.</p>
 305
 306 <p>In addition to the regular Programs tests, the Programs tree also provides a
 307 mechanism for compiling the programs in different ways.  If the variable TEST is
 308 defined on the gmake command line, the test system will include a Makefile named
 309 <tt>TEST.&lt;value of TEST variable&gt;.Makefile</tt>.  This Makefile can modify
 310 build rules to yield different results.</p>
 311
 312 <p>For example, the LLVM nightly tester uses <tt>TEST.nightly.Makefile</tt> to
 313 create the nightly test reports.  To run the nightly tests, run <tt>gmake
 314 TEST=nightly</tt>.</p>
 315
 316 <p>There are several TEST Makefiles available in the tree.  Some of them are
 317 designed for internal LLVM research and will not work outside of the LLVM
 318 research group.  They may still be valuable, however, as a guide to writing your
 319 own TEST Makefile for any optimization or analysis passes that you develop with
 320 LLVM.</p>
 321
 322 </div>
 323
 324 <!--===============================================================-->
 325 <div class="doc_section"><a name="run">Running the LLVM Tests</a></div>
 326 <!--===============================================================-->
 327
 328 <div class="doc_text">
 329
 330 <p>First, all tests are executed within the LLVM object directory tree.  They
 331 <i>are not</i> executed inside of the LLVM source tree.  This is because the
 332 test suite creates temporary files during execution.  </p>
 333
 334 <p>The master Makefile in llvm/test is capable of running both the QMTest driven
 335 tests and the Programs tests.  By default, it will run all of the tests.</p>
 336
 337 <p>To run only the QMTest driven tests, run <tt>gmake qmtest</tt> at the
 338 command line in llvm/tests.  To run a specific qmtest, suffix the test name with
 339 ".t" when running gmake.</p>
 340
 341 <p>For example, to run the Regression.LLC tests, type <tt>gmake
 342 Regression.LLC.t</tt> in llvm/tests.</p>
 343
 344 <p>Note that the Makefiles in llvm/test/Features and llvm/test/Regression are
 345 gone. You must now use QMTest from the llvm/test directory to run them.</p>
 346
 347 <p>To run the Programs test, cd into the llvm/test/Programs directory and type
 348 <tt>gmake</tt>.  Alternatively, you can type <tt>gmake TEST=&lt;type&gt;
 349 test</tt> to run one of the specialized tests in
 350 llvm/test/Programs/TEST.&lt;type&gt;.Makefile. For example, you could run the
 351 nightly tester tests using the following commands:</p>
 352
 353 <pre>
 354  % cd llvm/test/Programs
 355  % gmake TEST=nightly test
 356 </pre>
 357
 358 <p>Regardless of which test you're running, the results are printed on standard
 359 output and standard error.  You can redirect these results to a file if you
 360 choose.</p>
 361
 362 <p>Some tests are known to fail.  Some are bugs that we have not fixed yet;
 363 others are features that we haven't added yet (or may never add).  In QMTest,
 364 the result for such tests will be XFAIL (eXpected FAILure).  In this way, you
 365 can tell the difference between an expected and unexpected failure.</p>
 366
 367 <p>The Programs tests have no such feature as of this time. If the test passes,
 368 only warnings and other miscellaneous output will be generated.  If a test
 369 fails, a large &lt;program&gt; FAILED message will be displayed.  This will help
 370 you separate benign warnings from actual test failures.</p>
 371
 372 </div>
 373
 374 <!-- *********************************************************************** -->
 375
 376 <hr>
 377 <address>
 378   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
 379   src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
 380   <a href="http://validator.w3.org/check/referer"><img
 381   src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
 382
 383   John T. Criswell<br>
 384   <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
 385   Last modified: $Date$
 386 </address>
 387 </body>
 388 </html>