[ARM] Identity shuffles are legal
[llvm-complete.git] / docs / TestingGuide.rst
blobf147a9fbd7ab3c924218eae057c2d70411cb9856
1 =================================
2 LLVM Testing Infrastructure Guide
3 =================================
5 .. contents::
6    :local:
8 .. toctree::
9    :hidden:
11    TestSuiteGuide
12    TestSuiteMakefileGuide
14 Overview
15 ========
17 This document is the reference manual for the LLVM testing
18 infrastructure. It documents the structure of the LLVM testing
19 infrastructure, the tools needed to use it, and how to add and run
20 tests.
22 Requirements
23 ============
25 In order to use the LLVM testing infrastructure, you will need all of the
26 software required to build LLVM, as well as `Python <http://python.org>`_ 2.7 or
27 later.
29 LLVM Testing Infrastructure Organization
30 ========================================
32 The LLVM testing infrastructure contains three major categories of tests:
33 unit tests, regression tests and whole programs. The unit tests and regression
34 tests are contained inside the LLVM repository itself under ``llvm/unittests``
35 and ``llvm/test`` respectively and are expected to always pass -- they should be
36 run before every commit.
38 The whole programs tests are referred to as the "LLVM test suite" (or
39 "test-suite") and are in the ``test-suite`` module in subversion. For
40 historical reasons, these tests are also referred to as the "nightly
41 tests" in places, which is less ambiguous than "test-suite" and remains
42 in use although we run them much more often than nightly.
44 Unit tests
45 ----------
47 Unit tests are written using `Google Test <https://github.com/google/googletest/blob/master/googletest/docs/primer.md>`_
48 and `Google Mock <https://github.com/google/googletest/blob/master/googlemock/docs/ForDummies.md>`_
49 and are located in the ``llvm/unittests`` directory.
51 Regression tests
52 ----------------
54 The regression tests are small pieces of code that test a specific
55 feature of LLVM or trigger a specific bug in LLVM. The language they are
56 written in depends on the part of LLVM being tested. These tests are driven by
57 the :doc:`Lit <CommandGuide/lit>` testing tool (which is part of LLVM), and
58 are located in the ``llvm/test`` directory.
60 Typically when a bug is found in LLVM, a regression test containing just
61 enough code to reproduce the problem should be written and placed
62 somewhere underneath this directory. For example, it can be a small
63 piece of LLVM IR distilled from an actual application or benchmark.
65 ``test-suite``
66 --------------
68 The test suite contains whole programs, which are pieces of code which
69 can be compiled and linked into a stand-alone program that can be
70 executed. These programs are generally written in high level languages
71 such as C or C++.
73 These programs are compiled using a user specified compiler and set of
74 flags, and then executed to capture the program output and timing
75 information. The output of these programs is compared to a reference
76 output to ensure that the program is being compiled correctly.
78 In addition to compiling and executing programs, whole program tests
79 serve as a way of benchmarking LLVM performance, both in terms of the
80 efficiency of the programs generated as well as the speed with which
81 LLVM compiles, optimizes, and generates code.
83 The test-suite is located in the ``test-suite`` Subversion module.
85 See the :doc:`TestSuiteGuide` for details.
87 Debugging Information tests
88 ---------------------------
90 The test suite contains tests to check quality of debugging information.
91 The test are written in C based languages or in LLVM assembly language.
93 These tests are compiled and run under a debugger. The debugger output
94 is checked to validate of debugging information. See README.txt in the
95 test suite for more information. This test suite is located in the
96 ``debuginfo-tests`` Subversion module.
98 Quick start
99 ===========
101 The tests are located in two separate Subversion modules. The unit and
102 regression tests are in the main "llvm" module under the directories
103 ``llvm/unittests`` and ``llvm/test`` (so you get these tests for free with the
104 main LLVM tree). Use ``make check-all`` to run the unit and regression tests
105 after building LLVM.
107 The ``test-suite`` module contains more comprehensive tests including whole C
108 and C++ programs. See the :doc:`TestSuiteGuide` for details.
110 Unit and Regression tests
111 -------------------------
113 To run all of the LLVM unit tests use the check-llvm-unit target:
115 .. code-block:: bash
117     % make check-llvm-unit
119 To run all of the LLVM regression tests use the check-llvm target:
121 .. code-block:: bash
123     % make check-llvm
125 In order to get reasonable testing performance, build LLVM and subprojects
126 in release mode, i.e.
128 .. code-block:: bash
130     % cmake -DCMAKE_BUILD_TYPE="Release" -DLLVM_ENABLE_ASSERTIONS=On
132 If you have `Clang <http://clang.llvm.org/>`_ checked out and built, you
133 can run the LLVM and Clang tests simultaneously using:
135 .. code-block:: bash
137     % make check-all
139 To run the tests with Valgrind (Memcheck by default), use the ``LIT_ARGS`` make
140 variable to pass the required options to lit. For example, you can use:
142 .. code-block:: bash
144     % make check LIT_ARGS="-v --vg --vg-leak"
146 to enable testing with valgrind and with leak checking enabled.
148 To run individual tests or subsets of tests, you can use the ``llvm-lit``
149 script which is built as part of LLVM. For example, to run the
150 ``Integer/BitPacked.ll`` test by itself you can run:
152 .. code-block:: bash
154     % llvm-lit ~/llvm/test/Integer/BitPacked.ll 
156 or to run all of the ARM CodeGen tests:
158 .. code-block:: bash
160     % llvm-lit ~/llvm/test/CodeGen/ARM
162 For more information on using the :program:`lit` tool, see ``llvm-lit --help``
163 or the :doc:`lit man page <CommandGuide/lit>`.
165 Debugging Information tests
166 ---------------------------
168 To run debugging information tests simply add the ``debuginfo-tests``
169 project to your ``LLVM_ENABLE_PROJECTS`` define on the cmake
170 command-line.
172 Regression test structure
173 =========================
175 The LLVM regression tests are driven by :program:`lit` and are located in the
176 ``llvm/test`` directory.
178 This directory contains a large array of small tests that exercise
179 various features of LLVM and to ensure that regressions do not occur.
180 The directory is broken into several sub-directories, each focused on a
181 particular area of LLVM.
183 Writing new regression tests
184 ----------------------------
186 The regression test structure is very simple, but does require some
187 information to be set. This information is gathered via ``configure``
188 and is written to a file, ``test/lit.site.cfg`` in the build directory.
189 The ``llvm/test`` Makefile does this work for you.
191 In order for the regression tests to work, each directory of tests must
192 have a ``lit.local.cfg`` file. :program:`lit` looks for this file to determine
193 how to run the tests. This file is just Python code and thus is very
194 flexible, but we've standardized it for the LLVM regression tests. If
195 you're adding a directory of tests, just copy ``lit.local.cfg`` from
196 another directory to get running. The standard ``lit.local.cfg`` simply
197 specifies which files to look in for tests. Any directory that contains
198 only directories does not need the ``lit.local.cfg`` file. Read the :doc:`Lit
199 documentation <CommandGuide/lit>` for more information.
201 Each test file must contain lines starting with "RUN:" that tell :program:`lit`
202 how to run it. If there are no RUN lines, :program:`lit` will issue an error
203 while running a test.
205 RUN lines are specified in the comments of the test program using the
206 keyword ``RUN`` followed by a colon, and lastly the command (pipeline)
207 to execute. Together, these lines form the "script" that :program:`lit`
208 executes to run the test case. The syntax of the RUN lines is similar to a
209 shell's syntax for pipelines including I/O redirection and variable
210 substitution. However, even though these lines may *look* like a shell
211 script, they are not. RUN lines are interpreted by :program:`lit`.
212 Consequently, the syntax differs from shell in a few ways. You can specify
213 as many RUN lines as needed.
215 :program:`lit` performs substitution on each RUN line to replace LLVM tool names
216 with the full paths to the executable built for each tool (in
217 ``$(LLVM_OBJ_ROOT)/$(BuildMode)/bin)``. This ensures that :program:`lit` does
218 not invoke any stray LLVM tools in the user's path during testing.
220 Each RUN line is executed on its own, distinct from other lines unless
221 its last character is ``\``. This continuation character causes the RUN
222 line to be concatenated with the next one. In this way you can build up
223 long pipelines of commands without making huge line lengths. The lines
224 ending in ``\`` are concatenated until a RUN line that doesn't end in
225 ``\`` is found. This concatenated set of RUN lines then constitutes one
226 execution. :program:`lit` will substitute variables and arrange for the pipeline
227 to be executed. If any process in the pipeline fails, the entire line (and
228 test case) fails too.
230 Below is an example of legal RUN lines in a ``.ll`` file:
232 .. code-block:: llvm
234     ; RUN: llvm-as < %s | llvm-dis > %t1
235     ; RUN: llvm-dis < %s.bc-13 > %t2
236     ; RUN: diff %t1 %t2
238 As with a Unix shell, the RUN lines permit pipelines and I/O
239 redirection to be used.
241 There are some quoting rules that you must pay attention to when writing
242 your RUN lines. In general nothing needs to be quoted. :program:`lit` won't
243 strip off any quote characters so they will get passed to the invoked program.
244 To avoid this use curly braces to tell :program:`lit` that it should treat
245 everything enclosed as one value.
247 In general, you should strive to keep your RUN lines as simple as possible,
248 using them only to run tools that generate textual output you can then examine.
249 The recommended way to examine output to figure out if the test passes is using
250 the :doc:`FileCheck tool <CommandGuide/FileCheck>`. *[The usage of grep in RUN
251 lines is deprecated - please do not send or commit patches that use it.]*
253 Put related tests into a single file rather than having a separate file per
254 test. Check if there are files already covering your feature and consider
255 adding your code there instead of creating a new file.
257 Extra files
258 -----------
260 If your test requires extra files besides the file containing the ``RUN:``
261 lines, the idiomatic place to put them is in a subdirectory ``Inputs``.
262 You can then refer to the extra files as ``%S/Inputs/foo.bar``.
264 For example, consider ``test/Linker/ident.ll``. The directory structure is
265 as follows::
267   test/
268     Linker/
269       ident.ll
270       Inputs/
271         ident.a.ll
272         ident.b.ll
274 For convenience, these are the contents:
276 .. code-block:: llvm
278   ;;;;; ident.ll:
280   ; RUN: llvm-link %S/Inputs/ident.a.ll %S/Inputs/ident.b.ll -S | FileCheck %s
282   ; Verify that multiple input llvm.ident metadata are linked together.
284   ; CHECK-DAG: !llvm.ident = !{!0, !1, !2}
285   ; CHECK-DAG: "Compiler V1"
286   ; CHECK-DAG: "Compiler V2"
287   ; CHECK-DAG: "Compiler V3"
289   ;;;;; Inputs/ident.a.ll:
291   !llvm.ident = !{!0, !1}
292   !0 = metadata !{metadata !"Compiler V1"}
293   !1 = metadata !{metadata !"Compiler V2"}
295   ;;;;; Inputs/ident.b.ll:
297   !llvm.ident = !{!0}
298   !0 = metadata !{metadata !"Compiler V3"}
300 For symmetry reasons, ``ident.ll`` is just a dummy file that doesn't
301 actually participate in the test besides holding the ``RUN:`` lines.
303 .. note::
305   Some existing tests use ``RUN: true`` in extra files instead of just
306   putting the extra files in an ``Inputs/`` directory. This pattern is
307   deprecated.
309 Fragile tests
310 -------------
312 It is easy to write a fragile test that would fail spuriously if the tool being
313 tested outputs a full path to the input file.  For example, :program:`opt` by
314 default outputs a ``ModuleID``:
316 .. code-block:: console
318   $ cat example.ll
319   define i32 @main() nounwind {
320       ret i32 0
321   }
323   $ opt -S /path/to/example.ll
324   ; ModuleID = '/path/to/example.ll'
326   define i32 @main() nounwind {
327       ret i32 0
328   }
330 ``ModuleID`` can unexpectedly match against ``CHECK`` lines.  For example:
332 .. code-block:: llvm
334   ; RUN: opt -S %s | FileCheck
336   define i32 @main() nounwind {
337       ; CHECK-NOT: load
338       ret i32 0
339   }
341 This test will fail if placed into a ``download`` directory.
343 To make your tests robust, always use ``opt ... < %s`` in the RUN line.
344 :program:`opt` does not output a ``ModuleID`` when input comes from stdin.
346 Platform-Specific Tests
347 -----------------------
349 Whenever adding tests that require the knowledge of a specific platform,
350 either related to code generated, specific output or back-end features,
351 you must make sure to isolate the features, so that buildbots that
352 run on different architectures (and don't even compile all back-ends),
353 don't fail.
355 The first problem is to check for target-specific output, for example sizes
356 of structures, paths and architecture names, for example:
358 * Tests containing Windows paths will fail on Linux and vice-versa.
359 * Tests that check for ``x86_64`` somewhere in the text will fail anywhere else.
360 * Tests where the debug information calculates the size of types and structures.
362 Also, if the test rely on any behaviour that is coded in any back-end, it must
363 go in its own directory. So, for instance, code generator tests for ARM go
364 into ``test/CodeGen/ARM`` and so on. Those directories contain a special
365 ``lit`` configuration file that ensure all tests in that directory will
366 only run if a specific back-end is compiled and available.
368 For instance, on ``test/CodeGen/ARM``, the ``lit.local.cfg`` is:
370 .. code-block:: python
372   config.suffixes = ['.ll', '.c', '.cpp', '.test']
373   if not 'ARM' in config.root.targets:
374     config.unsupported = True
376 Other platform-specific tests are those that depend on a specific feature
377 of a specific sub-architecture, for example only to Intel chips that support ``AVX2``.
379 For instance, ``test/CodeGen/X86/psubus.ll`` tests three sub-architecture
380 variants:
382 .. code-block:: llvm
384   ; RUN: llc -mcpu=core2 < %s | FileCheck %s -check-prefix=SSE2
385   ; RUN: llc -mcpu=corei7-avx < %s | FileCheck %s -check-prefix=AVX1
386   ; RUN: llc -mcpu=core-avx2 < %s | FileCheck %s -check-prefix=AVX2
388 And the checks are different:
390 .. code-block:: llvm
392   ; SSE2: @test1
393   ; SSE2: psubusw LCPI0_0(%rip), %xmm0
394   ; AVX1: @test1
395   ; AVX1: vpsubusw LCPI0_0(%rip), %xmm0, %xmm0
396   ; AVX2: @test1
397   ; AVX2: vpsubusw LCPI0_0(%rip), %xmm0, %xmm0
399 So, if you're testing for a behaviour that you know is platform-specific or
400 depends on special features of sub-architectures, you must add the specific
401 triple, test with the specific FileCheck and put it into the specific
402 directory that will filter out all other architectures.
405 Constraining test execution
406 ---------------------------
408 Some tests can be run only in specific configurations, such as
409 with debug builds or on particular platforms. Use ``REQUIRES``
410 and ``UNSUPPORTED`` to control when the test is enabled.
412 Some tests are expected to fail. For example, there may be a known bug
413 that the test detect. Use ``XFAIL`` to mark a test as an expected failure.
414 An ``XFAIL`` test will be successful if its execution fails, and
415 will be a failure if its execution succeeds.
417 .. code-block:: llvm
419     ; This test will be only enabled in the build with asserts.
420     ; REQUIRES: asserts
421     ; This test is disabled on Linux.
422     ; UNSUPPORTED: -linux-
423     ; This test is expected to fail on PowerPC.
424     ; XFAIL: powerpc
426 ``REQUIRES`` and ``UNSUPPORTED`` and ``XFAIL`` all accept a comma-separated
427 list of boolean expressions. The values in each expression may be:
429 - Features added to ``config.available_features`` by 
430   configuration files such as ``lit.cfg``.
431 - Substrings of the target triple (``UNSUPPORTED`` and ``XFAIL`` only).
433 | ``REQUIRES`` enables the test if all expressions are true.
434 | ``UNSUPPORTED`` disables the test if any expression is true.
435 | ``XFAIL`` expects the test to fail if any expression is true.
437 As a special case, ``XFAIL: *`` is expected to fail everywhere.
439 .. code-block:: llvm
441     ; This test is disabled on Windows,
442     ; and is disabled on Linux, except for Android Linux.
443     ; UNSUPPORTED: windows, linux && !android
444     ; This test is expected to fail on both PowerPC and ARM.
445     ; XFAIL: powerpc || arm
448 Substitutions
449 -------------
451 Besides replacing LLVM tool names the following substitutions are performed in
452 RUN lines:
454 ``%%``
455    Replaced by a single ``%``. This allows escaping other substitutions.
457 ``%s``
458    File path to the test case's source. This is suitable for passing on the
459    command line as the input to an LLVM tool.
461    Example: ``/home/user/llvm/test/MC/ELF/foo_test.s``
463 ``%S``
464    Directory path to the test case's source.
466    Example: ``/home/user/llvm/test/MC/ELF``
468 ``%t``
469    File path to a temporary file name that could be used for this test case.
470    The file name won't conflict with other test cases. You can append to it
471    if you need multiple temporaries. This is useful as the destination of
472    some redirected output.
474    Example: ``/home/user/llvm.build/test/MC/ELF/Output/foo_test.s.tmp``
476 ``%T``
477    Directory of ``%t``. Deprecated. Shouldn't be used, because it can be easily
478    misused and cause race conditions between tests.
480    Use ``rm -rf %t && mkdir %t`` instead if a temporary directory is necessary.
482    Example: ``/home/user/llvm.build/test/MC/ELF/Output``
484 ``%{pathsep}``
486    Expands to the path separator, i.e. ``:`` (or ``;`` on Windows).
488 ``%/s, %/S, %/t, %/T:``
490   Act like the corresponding substitution above but replace any ``\``
491   character with a ``/``. This is useful to normalize path separators.
493    Example: ``%s:  C:\Desktop Files/foo_test.s.tmp``
494    
495    Example: ``%/s: C:/Desktop Files/foo_test.s.tmp``
497 ``%:s, %:S, %:t, %:T:``
499   Act like the corresponding substitution above but remove colons at
500   the beginning of Windows paths. This is useful to allow concatenation
501   of absolute paths on Windows to produce a legal path.
503    Example: ``%s:  C:\Desktop Files\foo_test.s.tmp``
505    Example: ``%:s: C\Desktop Files\foo_test.s.tmp``
508 **LLVM-specific substitutions:**
510 ``%shlibext``
511    The suffix for the host platforms shared library files. This includes the
512    period as the first character.
514    Example: ``.so`` (Linux), ``.dylib`` (macOS), ``.dll`` (Windows)
516 ``%exeext``
517    The suffix for the host platforms executable files. This includes the
518    period as the first character.
520    Example: ``.exe`` (Windows), empty on Linux.
522 ``%(line)``, ``%(line+<number>)``, ``%(line-<number>)``
523    The number of the line where this substitution is used, with an optional
524    integer offset. This can be used in tests with multiple RUN lines, which
525    reference test file's line numbers.
528 **Clang-specific substitutions:**
530 ``%clang``
531    Invokes the Clang driver.
533 ``%clang_cpp``
534    Invokes the Clang driver for C++.
536 ``%clang_cl``
537    Invokes the CL-compatible Clang driver.
539 ``%clangxx``
540    Invokes the G++-compatible Clang driver.
542 ``%clang_cc1``
543    Invokes the Clang frontend.
545 ``%itanium_abi_triple``, ``%ms_abi_triple``
546    These substitutions can be used to get the current target triple adjusted to
547    the desired ABI. For example, if the test suite is running with the
548    ``i686-pc-win32`` target, ``%itanium_abi_triple`` will expand to
549    ``i686-pc-mingw32``. This allows a test to run with a specific ABI without
550    constraining it to a specific triple.
552 To add more substituations, look at ``test/lit.cfg`` or ``lit.local.cfg``.
555 Options
556 -------
558 The llvm lit configuration allows to customize some things with user options:
560 ``llc``, ``opt``, ...
561     Substitute the respective llvm tool name with a custom command line. This
562     allows to specify custom paths and default arguments for these tools.
563     Example:
565     % llvm-lit "-Dllc=llc -verify-machineinstrs"
567 ``run_long_tests``
568     Enable the execution of long running tests.
570 ``llvm_site_config``
571     Load the specified lit configuration instead of the default one.
574 Other Features
575 --------------
577 To make RUN line writing easier, there are several helper programs. These
578 helpers are in the PATH when running tests, so you can just call them using
579 their name. For example:
581 ``not``
582    This program runs its arguments and then inverts the result code from it.
583    Zero result codes become 1. Non-zero result codes become 0.
585 To make the output more useful, :program:`lit` will scan
586 the lines of the test case for ones that contain a pattern that matches
587 ``PR[0-9]+``. This is the syntax for specifying a PR (Problem Report) number
588 that is related to the test case. The number after "PR" specifies the
589 LLVM bugzilla number. When a PR number is specified, it will be used in
590 the pass/fail reporting. This is useful to quickly get some context when
591 a test fails.
593 Finally, any line that contains "END." will cause the special
594 interpretation of lines to terminate. This is generally done right after
595 the last RUN: line. This has two side effects:
597 (a) it prevents special interpretation of lines that are part of the test
598     program, not the instructions to the test case, and
600 (b) it speeds things up for really big test cases by avoiding
601     interpretation of the remainder of the file.