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