docs/TestSuiteMakefileGuide.rst

   1 ======================================
   2 test-suite Makefile Guide (deprecated)
   3 ======================================
   4
   5 .. contents::
   6     :local:
   7
   8 Overview
   9 ========
  10
  11 First, all tests are executed within the LLVM object directory tree.
  12 They *are not* executed inside of the LLVM source tree. This is because
  13 the test suite creates temporary files during execution.
  14
  15 To run the test suite, you need to use the following steps:
  16
  17 #. Check out the ``test-suite`` module with:
  18
  19    .. code-block:: bash
  20
  21        % git clone https://github.com/llvm/llvm-test-suite.git test-suite
  22
  23 #. FIXME: these directions are outdated and won't work. Figure out
  24    what the correct thing to do is, and write it down here.
  25
  26 #. Configure and build ``llvm``.
  27
  28 #. Configure and build ``llvm-gcc``.
  29
  30 #. Install ``llvm-gcc`` somewhere.
  31
  32 #. *Re-configure* ``llvm`` from the top level of each build tree (LLVM
  33    object directory tree) in which you want to run the test suite, just
  34    as you do before building LLVM.
  35
  36    During the *re-configuration*, you must either: (1) have ``llvm-gcc``
  37    you just built in your path, or (2) specify the directory where your
  38    just-built ``llvm-gcc`` is installed using
  39    ``--with-llvmgccdir=$LLVM_GCC_DIR``.
  40
  41    You must also tell the configure machinery that the test suite is
  42    available so it can be configured for your build tree:
  43
  44    .. code-block:: bash
  45
  46        % cd $LLVM_OBJ_ROOT ; $LLVM_SRC_ROOT/configure [--with-llvmgccdir=$LLVM_GCC_DIR]
  47
  48    [Remember that ``$LLVM_GCC_DIR`` is the directory where you
  49    *installed* llvm-gcc, not its src or obj directory.]
  50
  51 #. You can now run the test suite from your build tree as follows:
  52
  53    .. code-block:: bash
  54
  55        % cd $LLVM_OBJ_ROOT/projects/test-suite
  56        % make
  57
  58 Note that the second and third steps only need to be done once. After
  59 you have the suite checked out and configured, you don't need to do it
  60 again (unless the test code or configure script changes).
  61
  62 Configuring External Tests
  63 ==========================
  64
  65 In order to run the External tests in the ``test-suite`` module, you
  66 must specify *--with-externals*. This must be done during the
  67 *re-configuration* step (see above), and the ``llvm`` re-configuration
  68 must recognize the previously-built ``llvm-gcc``. If any of these is
  69 missing or neglected, the External tests won't work.
  70
  71 * *--with-externals*
  72
  73 * *--with-externals=<directory>*
  74
  75 This tells LLVM where to find any external tests. They are expected to
  76 be in specifically named subdirectories of <``directory``>. If
  77 ``directory`` is left unspecified, ``configure`` uses the default value
  78 ``/home/vadve/shared/benchmarks/speccpu2000/benchspec``. Subdirectory
  79 names known to LLVM include:
  80
  81 * spec95
  82
  83 * speccpu2000
  84
  85 * speccpu2006
  86
  87 * povray31
  88
  89 Others are added from time to time, and can be determined from
  90 ``configure``.
  91
  92 Running Different Tests
  93 =======================
  94
  95 In addition to the regular "whole program" tests, the ``test-suite``
  96 module also provides a mechanism for compiling the programs in different
  97 ways. If the variable TEST is defined on the ``gmake`` command line, the
  98 test system will include a Makefile named
  99 ``TEST.<value of TEST variable>.Makefile``. This Makefile can modify
 100 build rules to yield different results.
 101
 102 For example, the LLVM nightly tester uses ``TEST.nightly.Makefile`` to
 103 create the nightly test reports. To run the nightly tests, run
 104 ``gmake TEST=nightly``.
 105
 106 There are several TEST Makefiles available in the tree. Some of them are
 107 designed for internal LLVM research and will not work outside of the
 108 LLVM research group. They may still be valuable, however, as a guide to
 109 writing your own TEST Makefile for any optimization or analysis passes
 110 that you develop with LLVM.
 111
 112 Generating Test Output
 113 ======================
 114
 115 There are a number of ways to run the tests and generate output. The
 116 most simple one is simply running ``gmake`` with no arguments. This will
 117 compile and run all programs in the tree using a number of different
 118 methods and compare results. Any failures are reported in the output,
 119 but are likely drowned in the other output. Passes are not reported
 120 explicitly.
 121
 122 Somewhat better is running ``gmake TEST=sometest test``, which runs the
 123 specified test and usually adds per-program summaries to the output
 124 (depending on which sometest you use). For example, the ``nightly`` test
 125 explicitly outputs TEST-PASS or TEST-FAIL for every test after each
 126 program. Though these lines are still drowned in the output, it's easy
 127 to grep the output logs in the Output directories.
 128
 129 Even better are the ``report`` and ``report.format`` targets (where
 130 ``format`` is one of ``html``, ``csv``, ``text`` or ``graphs``). The
 131 exact contents of the report are dependent on which ``TEST`` you are
 132 running, but the text results are always shown at the end of the run and
 133 the results are always stored in the ``report.<type>.format`` file (when
 134 running with ``TEST=<type>``). The ``report`` also generate a file
 135 called ``report.<type>.raw.out`` containing the output of the entire
 136 test run.
 137
 138 Writing Custom Tests for the test-suite
 139 =======================================
 140
 141 Assuming you can run the test suite, (e.g.
 142 "``gmake TEST=nightly report``" should work), it is really easy to run
 143 optimizations or code generator components against every program in the
 144 tree, collecting statistics or running custom checks for correctness. At
 145 base, this is how the nightly tester works, it's just one example of a
 146 general framework.
 147
 148 Lets say that you have an LLVM optimization pass, and you want to see
 149 how many times it triggers. First thing you should do is add an LLVM
 150 `statistic <ProgrammersManual.html#Statistic>`_ to your pass, which will
 151 tally counts of things you care about.
 152
 153 Following this, you can set up a test and a report that collects these
 154 and formats them for easy viewing. This consists of two files, a
 155 "``test-suite/TEST.XXX.Makefile``" fragment (where XXX is the name of
 156 your test) and a "``test-suite/TEST.XXX.report``" file that indicates
 157 how to format the output into a table. There are many example reports of
 158 various levels of sophistication included with the test suite, and the
 159 framework is very general.
 160
 161 If you are interested in testing an optimization pass, check out the
 162 "libcalls" test as an example. It can be run like this:
 163
 164 .. code-block:: bash
 165
 166     % cd llvm/projects/test-suite/MultiSource/Benchmarks  # or some other level
 167     % make TEST=libcalls report
 168
 169 This will do a bunch of stuff, then eventually print a table like this:
 170
 171 ::
 172
 173     Name                                  | total | #exit |
 174     ...
 175     FreeBench/analyzer/analyzer           | 51    | 6     |
 176     FreeBench/fourinarow/fourinarow       | 1     | 1     |
 177     FreeBench/neural/neural               | 19    | 9     |
 178     FreeBench/pifft/pifft                 | 5     | 3     |
 179     MallocBench/cfrac/cfrac               | 1     | *     |
 180     MallocBench/espresso/espresso         | 52    | 12    |
 181     MallocBench/gs/gs                     | 4     | *     |
 182     Prolangs-C/TimberWolfMC/timberwolfmc  | 302   | *     |
 183     Prolangs-C/agrep/agrep                | 33    | 12    |
 184     Prolangs-C/allroots/allroots          | *     | *     |
 185     Prolangs-C/assembler/assembler        | 47    | *     |
 186     Prolangs-C/bison/mybison              | 74    | *     |
 187     ...
 188
 189 This basically is grepping the -stats output and displaying it in a
 190 table. You can also use the "TEST=libcalls report.html" target to get
 191 the table in HTML form, similarly for report.csv and report.tex.
 192
 193 The source for this is in ``test-suite/TEST.libcalls.*``. The format is
 194 pretty simple: the Makefile indicates how to run the test (in this case,
 195 "``opt -simplify-libcalls -stats``"), and the report contains one line
 196 for each column of the output. The first value is the header for the
 197 column and the second is the regex to grep the output of the command
 198 for. There are lots of example reports that can do fancy stuff.