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