forked from OSchip/llvm-project
				
			
		
			
				
	
	
		
			609 lines
		
	
	
		
			21 KiB
		
	
	
	
		
			ReStructuredText
		
	
	
	
			
		
		
	
	
			609 lines
		
	
	
		
			21 KiB
		
	
	
	
		
			ReStructuredText
		
	
	
	
=================================
 | 
						|
LLVM Testing Infrastructure Guide
 | 
						|
=================================
 | 
						|
 | 
						|
.. contents::
 | 
						|
   :local:
 | 
						|
 | 
						|
.. toctree::
 | 
						|
   :hidden:
 | 
						|
 | 
						|
   TestSuiteGuide
 | 
						|
   TestSuiteMakefileGuide
 | 
						|
 | 
						|
Overview
 | 
						|
========
 | 
						|
 | 
						|
This document is the reference manual for the LLVM testing
 | 
						|
infrastructure. It documents the structure of the LLVM testing
 | 
						|
infrastructure, the tools needed to use it, and how to add and run
 | 
						|
tests.
 | 
						|
 | 
						|
Requirements
 | 
						|
============
 | 
						|
 | 
						|
In order to use the LLVM testing infrastructure, you will need all of the
 | 
						|
software required to build LLVM, as well as `Python <http://python.org>`_ 2.7 or
 | 
						|
later.
 | 
						|
 | 
						|
LLVM Testing Infrastructure Organization
 | 
						|
========================================
 | 
						|
 | 
						|
The LLVM testing infrastructure contains three major categories of tests:
 | 
						|
unit tests, regression tests and whole programs. The unit tests and regression
 | 
						|
tests are contained inside the LLVM repository itself under ``llvm/unittests``
 | 
						|
and ``llvm/test`` respectively and are expected to always pass -- they should be
 | 
						|
run before every commit.
 | 
						|
 | 
						|
The whole programs tests are referred to as the "LLVM test suite" (or
 | 
						|
"test-suite") and are in the ``test-suite`` module in subversion. For
 | 
						|
historical reasons, these tests are also referred to as the "nightly
 | 
						|
tests" in places, which is less ambiguous than "test-suite" and remains
 | 
						|
in use although we run them much more often than nightly.
 | 
						|
 | 
						|
Unit tests
 | 
						|
----------
 | 
						|
 | 
						|
Unit tests are written using `Google Test <https://github.com/google/googletest/blob/master/googletest/docs/primer.md>`_
 | 
						|
and `Google Mock <https://github.com/google/googletest/blob/master/googlemock/docs/for_dummies.md>`_
 | 
						|
and are located in the ``llvm/unittests`` directory.
 | 
						|
 | 
						|
Regression tests
 | 
						|
----------------
 | 
						|
 | 
						|
The regression tests are small pieces of code that test a specific
 | 
						|
feature of LLVM or trigger a specific bug in LLVM. The language they are
 | 
						|
written in depends on the part of LLVM being tested. These tests are driven by
 | 
						|
the :doc:`Lit <CommandGuide/lit>` testing tool (which is part of LLVM), and
 | 
						|
are located in the ``llvm/test`` directory.
 | 
						|
 | 
						|
Typically when a bug is found in LLVM, a regression test containing just
 | 
						|
enough code to reproduce the problem should be written and placed
 | 
						|
somewhere underneath this directory. For example, it can be a small
 | 
						|
piece of LLVM IR distilled from an actual application or benchmark.
 | 
						|
 | 
						|
``test-suite``
 | 
						|
--------------
 | 
						|
 | 
						|
The test suite contains whole programs, which are pieces of code which
 | 
						|
can be compiled and linked into a stand-alone program that can be
 | 
						|
executed. These programs are generally written in high level languages
 | 
						|
such as C or C++.
 | 
						|
 | 
						|
These programs are compiled using a user specified compiler and set of
 | 
						|
flags, and then executed to capture the program output and timing
 | 
						|
information. The output of these programs is compared to a reference
 | 
						|
output to ensure that the program is being compiled correctly.
 | 
						|
 | 
						|
In addition to compiling and executing programs, whole program tests
 | 
						|
serve as a way of benchmarking LLVM performance, both in terms of the
 | 
						|
efficiency of the programs generated as well as the speed with which
 | 
						|
LLVM compiles, optimizes, and generates code.
 | 
						|
 | 
						|
The test-suite is located in the ``test-suite`` Subversion module.
 | 
						|
 | 
						|
See the :doc:`TestSuiteGuide` for details.
 | 
						|
 | 
						|
Debugging Information tests
 | 
						|
---------------------------
 | 
						|
 | 
						|
The test suite contains tests to check quality of debugging information.
 | 
						|
The test are written in C based languages or in LLVM assembly language.
 | 
						|
 | 
						|
These tests are compiled and run under a debugger. The debugger output
 | 
						|
is checked to validate of debugging information. See README.txt in the
 | 
						|
test suite for more information. This test suite is located in the
 | 
						|
``debuginfo-tests`` Subversion module.
 | 
						|
 | 
						|
Quick start
 | 
						|
===========
 | 
						|
 | 
						|
The tests are located in two separate Subversion modules. The unit and
 | 
						|
regression tests are in the main "llvm" module under the directories
 | 
						|
``llvm/unittests`` and ``llvm/test`` (so you get these tests for free with the
 | 
						|
main LLVM tree). Use ``make check-all`` to run the unit and regression tests
 | 
						|
after building LLVM.
 | 
						|
 | 
						|
The ``test-suite`` module contains more comprehensive tests including whole C
 | 
						|
and C++ programs. See the :doc:`TestSuiteGuide` for details.
 | 
						|
 | 
						|
Unit and Regression tests
 | 
						|
-------------------------
 | 
						|
 | 
						|
To run all of the LLVM unit tests use the check-llvm-unit target:
 | 
						|
 | 
						|
.. code-block:: bash
 | 
						|
 | 
						|
    % make check-llvm-unit
 | 
						|
 | 
						|
To run all of the LLVM regression tests use the check-llvm target:
 | 
						|
 | 
						|
.. code-block:: bash
 | 
						|
 | 
						|
    % make check-llvm
 | 
						|
 | 
						|
In order to get reasonable testing performance, build LLVM and subprojects
 | 
						|
in release mode, i.e.
 | 
						|
 | 
						|
.. code-block:: bash
 | 
						|
 | 
						|
    % cmake -DCMAKE_BUILD_TYPE="Release" -DLLVM_ENABLE_ASSERTIONS=On
 | 
						|
 | 
						|
If you have `Clang <http://clang.llvm.org/>`_ checked out and built, you
 | 
						|
can run the LLVM and Clang tests simultaneously using:
 | 
						|
 | 
						|
.. code-block:: bash
 | 
						|
 | 
						|
    % make check-all
 | 
						|
 | 
						|
To run the tests with Valgrind (Memcheck by default), use the ``LIT_ARGS`` make
 | 
						|
variable to pass the required options to lit. For example, you can use:
 | 
						|
 | 
						|
.. code-block:: bash
 | 
						|
 | 
						|
    % make check LIT_ARGS="-v --vg --vg-leak"
 | 
						|
 | 
						|
to enable testing with valgrind and with leak checking enabled.
 | 
						|
 | 
						|
To run individual tests or subsets of tests, you can use the ``llvm-lit``
 | 
						|
script which is built as part of LLVM. For example, to run the
 | 
						|
``Integer/BitPacked.ll`` test by itself you can run:
 | 
						|
 | 
						|
.. code-block:: bash
 | 
						|
 | 
						|
    % llvm-lit ~/llvm/test/Integer/BitPacked.ll 
 | 
						|
 | 
						|
or to run all of the ARM CodeGen tests:
 | 
						|
 | 
						|
.. code-block:: bash
 | 
						|
 | 
						|
    % llvm-lit ~/llvm/test/CodeGen/ARM
 | 
						|
 | 
						|
For more information on using the :program:`lit` tool, see ``llvm-lit --help``
 | 
						|
or the :doc:`lit man page <CommandGuide/lit>`.
 | 
						|
 | 
						|
Debugging Information tests
 | 
						|
---------------------------
 | 
						|
 | 
						|
To run debugging information tests simply add the ``debuginfo-tests``
 | 
						|
project to your ``LLVM_ENABLE_PROJECTS`` define on the cmake
 | 
						|
command-line.
 | 
						|
 | 
						|
Regression test structure
 | 
						|
=========================
 | 
						|
 | 
						|
The LLVM regression tests are driven by :program:`lit` and are located in the
 | 
						|
``llvm/test`` directory.
 | 
						|
 | 
						|
This directory contains a large array of small tests that exercise
 | 
						|
various features of LLVM and to ensure that regressions do not occur.
 | 
						|
The directory is broken into several sub-directories, each focused on a
 | 
						|
particular area of LLVM.
 | 
						|
 | 
						|
Writing new regression tests
 | 
						|
----------------------------
 | 
						|
 | 
						|
The regression test structure is very simple, but does require some
 | 
						|
information to be set. This information is gathered via ``configure``
 | 
						|
and is written to a file, ``test/lit.site.cfg`` in the build directory.
 | 
						|
The ``llvm/test`` Makefile does this work for you.
 | 
						|
 | 
						|
In order for the regression tests to work, each directory of tests must
 | 
						|
have a ``lit.local.cfg`` file. :program:`lit` looks for this file to determine
 | 
						|
how to run the tests. This file is just Python code and thus is very
 | 
						|
flexible, but we've standardized it for the LLVM regression tests. If
 | 
						|
you're adding a directory of tests, just copy ``lit.local.cfg`` from
 | 
						|
another directory to get running. The standard ``lit.local.cfg`` simply
 | 
						|
specifies which files to look in for tests. Any directory that contains
 | 
						|
only directories does not need the ``lit.local.cfg`` file. Read the :doc:`Lit
 | 
						|
documentation <CommandGuide/lit>` for more information.
 | 
						|
 | 
						|
Each test file must contain lines starting with "RUN:" that tell :program:`lit`
 | 
						|
how to run it. If there are no RUN lines, :program:`lit` will issue an error
 | 
						|
while running a test.
 | 
						|
 | 
						|
RUN lines are specified in the comments of the test program using the
 | 
						|
keyword ``RUN`` followed by a colon, and lastly the command (pipeline)
 | 
						|
to execute. Together, these lines form the "script" that :program:`lit`
 | 
						|
executes to run the test case. The syntax of the RUN lines is similar to a
 | 
						|
shell's syntax for pipelines including I/O redirection and variable
 | 
						|
substitution. However, even though these lines may *look* like a shell
 | 
						|
script, they are not. RUN lines are interpreted by :program:`lit`.
 | 
						|
Consequently, the syntax differs from shell in a few ways. You can specify
 | 
						|
as many RUN lines as needed.
 | 
						|
 | 
						|
:program:`lit` performs substitution on each RUN line to replace LLVM tool names
 | 
						|
with the full paths to the executable built for each tool (in
 | 
						|
``$(LLVM_OBJ_ROOT)/$(BuildMode)/bin)``. This ensures that :program:`lit` does
 | 
						|
not invoke any stray LLVM tools in the user's path during testing.
 | 
						|
 | 
						|
Each RUN line is executed on its own, distinct from other lines unless
 | 
						|
its last character is ``\``. This continuation character causes the RUN
 | 
						|
line to be concatenated with the next one. In this way you can build up
 | 
						|
long pipelines of commands without making huge line lengths. The lines
 | 
						|
ending in ``\`` are concatenated until a RUN line that doesn't end in
 | 
						|
``\`` is found. This concatenated set of RUN lines then constitutes one
 | 
						|
execution. :program:`lit` will substitute variables and arrange for the pipeline
 | 
						|
to be executed. If any process in the pipeline fails, the entire line (and
 | 
						|
test case) fails too.
 | 
						|
 | 
						|
Below is an example of legal RUN lines in a ``.ll`` file:
 | 
						|
 | 
						|
.. code-block:: llvm
 | 
						|
 | 
						|
    ; RUN: llvm-as < %s | llvm-dis > %t1
 | 
						|
    ; RUN: llvm-dis < %s.bc-13 > %t2
 | 
						|
    ; RUN: diff %t1 %t2
 | 
						|
 | 
						|
As with a Unix shell, the RUN lines permit pipelines and I/O
 | 
						|
redirection to be used.
 | 
						|
 | 
						|
There are some quoting rules that you must pay attention to when writing
 | 
						|
your RUN lines. In general nothing needs to be quoted. :program:`lit` won't
 | 
						|
strip off any quote characters so they will get passed to the invoked program.
 | 
						|
To avoid this use curly braces to tell :program:`lit` that it should treat
 | 
						|
everything enclosed as one value.
 | 
						|
 | 
						|
In general, you should strive to keep your RUN lines as simple as possible,
 | 
						|
using them only to run tools that generate textual output you can then examine.
 | 
						|
The recommended way to examine output to figure out if the test passes is using
 | 
						|
the :doc:`FileCheck tool <CommandGuide/FileCheck>`. *[The usage of grep in RUN
 | 
						|
lines is deprecated - please do not send or commit patches that use it.]*
 | 
						|
 | 
						|
Put related tests into a single file rather than having a separate file per
 | 
						|
test. Check if there are files already covering your feature and consider
 | 
						|
adding your code there instead of creating a new file.
 | 
						|
 | 
						|
Extra files
 | 
						|
-----------
 | 
						|
 | 
						|
If your test requires extra files besides the file containing the ``RUN:``
 | 
						|
lines, the idiomatic place to put them is in a subdirectory ``Inputs``.
 | 
						|
You can then refer to the extra files as ``%S/Inputs/foo.bar``.
 | 
						|
 | 
						|
For example, consider ``test/Linker/ident.ll``. The directory structure is
 | 
						|
as follows::
 | 
						|
 | 
						|
  test/
 | 
						|
    Linker/
 | 
						|
      ident.ll
 | 
						|
      Inputs/
 | 
						|
        ident.a.ll
 | 
						|
        ident.b.ll
 | 
						|
 | 
						|
For convenience, these are the contents:
 | 
						|
 | 
						|
.. code-block:: llvm
 | 
						|
 | 
						|
  ;;;;; ident.ll:
 | 
						|
 | 
						|
  ; RUN: llvm-link %S/Inputs/ident.a.ll %S/Inputs/ident.b.ll -S | FileCheck %s
 | 
						|
 | 
						|
  ; Verify that multiple input llvm.ident metadata are linked together.
 | 
						|
 | 
						|
  ; CHECK-DAG: !llvm.ident = !{!0, !1, !2}
 | 
						|
  ; CHECK-DAG: "Compiler V1"
 | 
						|
  ; CHECK-DAG: "Compiler V2"
 | 
						|
  ; CHECK-DAG: "Compiler V3"
 | 
						|
 | 
						|
  ;;;;; Inputs/ident.a.ll:
 | 
						|
 | 
						|
  !llvm.ident = !{!0, !1}
 | 
						|
  !0 = metadata !{metadata !"Compiler V1"}
 | 
						|
  !1 = metadata !{metadata !"Compiler V2"}
 | 
						|
 | 
						|
  ;;;;; Inputs/ident.b.ll:
 | 
						|
 | 
						|
  !llvm.ident = !{!0}
 | 
						|
  !0 = metadata !{metadata !"Compiler V3"}
 | 
						|
 | 
						|
For symmetry reasons, ``ident.ll`` is just a dummy file that doesn't
 | 
						|
actually participate in the test besides holding the ``RUN:`` lines.
 | 
						|
 | 
						|
.. note::
 | 
						|
 | 
						|
  Some existing tests use ``RUN: true`` in extra files instead of just
 | 
						|
  putting the extra files in an ``Inputs/`` directory. This pattern is
 | 
						|
  deprecated.
 | 
						|
 | 
						|
Fragile tests
 | 
						|
-------------
 | 
						|
 | 
						|
It is easy to write a fragile test that would fail spuriously if the tool being
 | 
						|
tested outputs a full path to the input file.  For example, :program:`opt` by
 | 
						|
default outputs a ``ModuleID``:
 | 
						|
 | 
						|
.. code-block:: console
 | 
						|
 | 
						|
  $ cat example.ll
 | 
						|
  define i32 @main() nounwind {
 | 
						|
      ret i32 0
 | 
						|
  }
 | 
						|
 | 
						|
  $ opt -S /path/to/example.ll
 | 
						|
  ; ModuleID = '/path/to/example.ll'
 | 
						|
 | 
						|
  define i32 @main() nounwind {
 | 
						|
      ret i32 0
 | 
						|
  }
 | 
						|
 | 
						|
``ModuleID`` can unexpectedly match against ``CHECK`` lines.  For example:
 | 
						|
 | 
						|
.. code-block:: llvm
 | 
						|
 | 
						|
  ; RUN: opt -S %s | FileCheck
 | 
						|
 | 
						|
  define i32 @main() nounwind {
 | 
						|
      ; CHECK-NOT: load
 | 
						|
      ret i32 0
 | 
						|
  }
 | 
						|
 | 
						|
This test will fail if placed into a ``download`` directory.
 | 
						|
 | 
						|
To make your tests robust, always use ``opt ... < %s`` in the RUN line.
 | 
						|
:program:`opt` does not output a ``ModuleID`` when input comes from stdin.
 | 
						|
 | 
						|
Platform-Specific Tests
 | 
						|
-----------------------
 | 
						|
 | 
						|
Whenever adding tests that require the knowledge of a specific platform,
 | 
						|
either related to code generated, specific output or back-end features,
 | 
						|
you must make sure to isolate the features, so that buildbots that
 | 
						|
run on different architectures (and don't even compile all back-ends),
 | 
						|
don't fail.
 | 
						|
 | 
						|
The first problem is to check for target-specific output, for example sizes
 | 
						|
of structures, paths and architecture names, for example:
 | 
						|
 | 
						|
* Tests containing Windows paths will fail on Linux and vice-versa.
 | 
						|
* Tests that check for ``x86_64`` somewhere in the text will fail anywhere else.
 | 
						|
* Tests where the debug information calculates the size of types and structures.
 | 
						|
 | 
						|
Also, if the test rely on any behaviour that is coded in any back-end, it must
 | 
						|
go in its own directory. So, for instance, code generator tests for ARM go
 | 
						|
into ``test/CodeGen/ARM`` and so on. Those directories contain a special
 | 
						|
``lit`` configuration file that ensure all tests in that directory will
 | 
						|
only run if a specific back-end is compiled and available.
 | 
						|
 | 
						|
For instance, on ``test/CodeGen/ARM``, the ``lit.local.cfg`` is:
 | 
						|
 | 
						|
.. code-block:: python
 | 
						|
 | 
						|
  config.suffixes = ['.ll', '.c', '.cpp', '.test']
 | 
						|
  if not 'ARM' in config.root.targets:
 | 
						|
    config.unsupported = True
 | 
						|
 | 
						|
Other platform-specific tests are those that depend on a specific feature
 | 
						|
of a specific sub-architecture, for example only to Intel chips that support ``AVX2``.
 | 
						|
 | 
						|
For instance, ``test/CodeGen/X86/psubus.ll`` tests three sub-architecture
 | 
						|
variants:
 | 
						|
 | 
						|
.. code-block:: llvm
 | 
						|
 | 
						|
  ; RUN: llc -mcpu=core2 < %s | FileCheck %s -check-prefix=SSE2
 | 
						|
  ; RUN: llc -mcpu=corei7-avx < %s | FileCheck %s -check-prefix=AVX1
 | 
						|
  ; RUN: llc -mcpu=core-avx2 < %s | FileCheck %s -check-prefix=AVX2
 | 
						|
 | 
						|
And the checks are different:
 | 
						|
 | 
						|
.. code-block:: llvm
 | 
						|
 | 
						|
  ; SSE2: @test1
 | 
						|
  ; SSE2: psubusw LCPI0_0(%rip), %xmm0
 | 
						|
  ; AVX1: @test1
 | 
						|
  ; AVX1: vpsubusw LCPI0_0(%rip), %xmm0, %xmm0
 | 
						|
  ; AVX2: @test1
 | 
						|
  ; AVX2: vpsubusw LCPI0_0(%rip), %xmm0, %xmm0
 | 
						|
 | 
						|
So, if you're testing for a behaviour that you know is platform-specific or
 | 
						|
depends on special features of sub-architectures, you must add the specific
 | 
						|
triple, test with the specific FileCheck and put it into the specific
 | 
						|
directory that will filter out all other architectures.
 | 
						|
 | 
						|
 | 
						|
Constraining test execution
 | 
						|
---------------------------
 | 
						|
 | 
						|
Some tests can be run only in specific configurations, such as
 | 
						|
with debug builds or on particular platforms. Use ``REQUIRES``
 | 
						|
and ``UNSUPPORTED`` to control when the test is enabled.
 | 
						|
 | 
						|
Some tests are expected to fail. For example, there may be a known bug
 | 
						|
that the test detect. Use ``XFAIL`` to mark a test as an expected failure.
 | 
						|
An ``XFAIL`` test will be successful if its execution fails, and
 | 
						|
will be a failure if its execution succeeds.
 | 
						|
 | 
						|
.. code-block:: llvm
 | 
						|
 | 
						|
    ; This test will be only enabled in the build with asserts.
 | 
						|
    ; REQUIRES: asserts
 | 
						|
    ; This test is disabled on Linux.
 | 
						|
    ; UNSUPPORTED: -linux-
 | 
						|
    ; This test is expected to fail on PowerPC.
 | 
						|
    ; XFAIL: powerpc
 | 
						|
 | 
						|
``REQUIRES`` and ``UNSUPPORTED`` and ``XFAIL`` all accept a comma-separated
 | 
						|
list of boolean expressions. The values in each expression may be:
 | 
						|
 | 
						|
- Features added to ``config.available_features`` by 
 | 
						|
  configuration files such as ``lit.cfg``.
 | 
						|
- Substrings of the target triple (``UNSUPPORTED`` and ``XFAIL`` only).
 | 
						|
 | 
						|
| ``REQUIRES`` enables the test if all expressions are true.
 | 
						|
| ``UNSUPPORTED`` disables the test if any expression is true.
 | 
						|
| ``XFAIL`` expects the test to fail if any expression is true.
 | 
						|
 | 
						|
As a special case, ``XFAIL: *`` is expected to fail everywhere.
 | 
						|
 | 
						|
.. code-block:: llvm
 | 
						|
 | 
						|
    ; This test is disabled on Windows,
 | 
						|
    ; and is disabled on Linux, except for Android Linux.
 | 
						|
    ; UNSUPPORTED: windows, linux && !android
 | 
						|
    ; This test is expected to fail on both PowerPC and ARM.
 | 
						|
    ; XFAIL: powerpc || arm
 | 
						|
 | 
						|
 | 
						|
Substitutions
 | 
						|
-------------
 | 
						|
 | 
						|
Besides replacing LLVM tool names the following substitutions are performed in
 | 
						|
RUN lines:
 | 
						|
 | 
						|
``%%``
 | 
						|
   Replaced by a single ``%``. This allows escaping other substitutions.
 | 
						|
 | 
						|
``%s``
 | 
						|
   File path to the test case's source. This is suitable for passing on the
 | 
						|
   command line as the input to an LLVM tool.
 | 
						|
 | 
						|
   Example: ``/home/user/llvm/test/MC/ELF/foo_test.s``
 | 
						|
 | 
						|
``%S``
 | 
						|
   Directory path to the test case's source.
 | 
						|
 | 
						|
   Example: ``/home/user/llvm/test/MC/ELF``
 | 
						|
 | 
						|
``%t``
 | 
						|
   File path to a temporary file name that could be used for this test case.
 | 
						|
   The file name won't conflict with other test cases. You can append to it
 | 
						|
   if you need multiple temporaries. This is useful as the destination of
 | 
						|
   some redirected output.
 | 
						|
 | 
						|
   Example: ``/home/user/llvm.build/test/MC/ELF/Output/foo_test.s.tmp``
 | 
						|
 | 
						|
``%T``
 | 
						|
   Directory of ``%t``. Deprecated. Shouldn't be used, because it can be easily
 | 
						|
   misused and cause race conditions between tests.
 | 
						|
 | 
						|
   Use ``rm -rf %t && mkdir %t`` instead if a temporary directory is necessary.
 | 
						|
 | 
						|
   Example: ``/home/user/llvm.build/test/MC/ELF/Output``
 | 
						|
 | 
						|
``%{pathsep}``
 | 
						|
 | 
						|
   Expands to the path separator, i.e. ``:`` (or ``;`` on Windows).
 | 
						|
 | 
						|
``%/s, %/S, %/t, %/T:``
 | 
						|
 | 
						|
  Act like the corresponding substitution above but replace any ``\``
 | 
						|
  character with a ``/``. This is useful to normalize path separators.
 | 
						|
 | 
						|
   Example: ``%s:  C:\Desktop Files/foo_test.s.tmp``
 | 
						|
   
 | 
						|
   Example: ``%/s: C:/Desktop Files/foo_test.s.tmp``
 | 
						|
 | 
						|
``%:s, %:S, %:t, %:T:``
 | 
						|
 | 
						|
  Act like the corresponding substitution above but remove colons at
 | 
						|
  the beginning of Windows paths. This is useful to allow concatenation
 | 
						|
  of absolute paths on Windows to produce a legal path.
 | 
						|
 | 
						|
   Example: ``%s:  C:\Desktop Files\foo_test.s.tmp``
 | 
						|
 | 
						|
   Example: ``%:s: C\Desktop Files\foo_test.s.tmp``
 | 
						|
 | 
						|
 | 
						|
**LLVM-specific substitutions:**
 | 
						|
 | 
						|
``%shlibext``
 | 
						|
   The suffix for the host platforms shared library files. This includes the
 | 
						|
   period as the first character.
 | 
						|
 | 
						|
   Example: ``.so`` (Linux), ``.dylib`` (macOS), ``.dll`` (Windows)
 | 
						|
 | 
						|
``%exeext``
 | 
						|
   The suffix for the host platforms executable files. This includes the
 | 
						|
   period as the first character.
 | 
						|
 | 
						|
   Example: ``.exe`` (Windows), empty on Linux.
 | 
						|
 | 
						|
``%(line)``, ``%(line+<number>)``, ``%(line-<number>)``
 | 
						|
   The number of the line where this substitution is used, with an optional
 | 
						|
   integer offset. This can be used in tests with multiple RUN lines, which
 | 
						|
   reference test file's line numbers.
 | 
						|
 | 
						|
 | 
						|
**Clang-specific substitutions:**
 | 
						|
 | 
						|
``%clang``
 | 
						|
   Invokes the Clang driver.
 | 
						|
 | 
						|
``%clang_cpp``
 | 
						|
   Invokes the Clang driver for C++.
 | 
						|
 | 
						|
``%clang_cl``
 | 
						|
   Invokes the CL-compatible Clang driver.
 | 
						|
 | 
						|
``%clangxx``
 | 
						|
   Invokes the G++-compatible Clang driver.
 | 
						|
 | 
						|
``%clang_cc1``
 | 
						|
   Invokes the Clang frontend.
 | 
						|
 | 
						|
``%itanium_abi_triple``, ``%ms_abi_triple``
 | 
						|
   These substitutions can be used to get the current target triple adjusted to
 | 
						|
   the desired ABI. For example, if the test suite is running with the
 | 
						|
   ``i686-pc-win32`` target, ``%itanium_abi_triple`` will expand to
 | 
						|
   ``i686-pc-mingw32``. This allows a test to run with a specific ABI without
 | 
						|
   constraining it to a specific triple.
 | 
						|
 | 
						|
**FileCheck-specific substitutions:**
 | 
						|
 | 
						|
``%ProtectFileCheckOutput``
 | 
						|
   This should precede a ``FileCheck`` call if and only if the call's textual
 | 
						|
   output affects test results.  It's usually easy to tell: just look for
 | 
						|
   redirection or piping of the ``FileCheck`` call's stdout or stderr.
 | 
						|
 | 
						|
To add more substituations, look at ``test/lit.cfg`` or ``lit.local.cfg``.
 | 
						|
 | 
						|
 | 
						|
Options
 | 
						|
-------
 | 
						|
 | 
						|
The llvm lit configuration allows to customize some things with user options:
 | 
						|
 | 
						|
``llc``, ``opt``, ...
 | 
						|
    Substitute the respective llvm tool name with a custom command line. This
 | 
						|
    allows to specify custom paths and default arguments for these tools.
 | 
						|
    Example:
 | 
						|
 | 
						|
    % llvm-lit "-Dllc=llc -verify-machineinstrs"
 | 
						|
 | 
						|
``run_long_tests``
 | 
						|
    Enable the execution of long running tests.
 | 
						|
 | 
						|
``llvm_site_config``
 | 
						|
    Load the specified lit configuration instead of the default one.
 | 
						|
 | 
						|
 | 
						|
Other Features
 | 
						|
--------------
 | 
						|
 | 
						|
To make RUN line writing easier, there are several helper programs. These
 | 
						|
helpers are in the PATH when running tests, so you can just call them using
 | 
						|
their name. For example:
 | 
						|
 | 
						|
``not``
 | 
						|
   This program runs its arguments and then inverts the result code from it.
 | 
						|
   Zero result codes become 1. Non-zero result codes become 0.
 | 
						|
 | 
						|
To make the output more useful, :program:`lit` will scan
 | 
						|
the lines of the test case for ones that contain a pattern that matches
 | 
						|
``PR[0-9]+``. This is the syntax for specifying a PR (Problem Report) number
 | 
						|
that is related to the test case. The number after "PR" specifies the
 | 
						|
LLVM bugzilla number. When a PR number is specified, it will be used in
 | 
						|
the pass/fail reporting. This is useful to quickly get some context when
 | 
						|
a test fails.
 | 
						|
 | 
						|
Finally, any line that contains "END." will cause the special
 | 
						|
interpretation of lines to terminate. This is generally done right after
 | 
						|
the last RUN: line. This has two side effects:
 | 
						|
 | 
						|
(a) it prevents special interpretation of lines that are part of the test
 | 
						|
    program, not the instructions to the test case, and
 | 
						|
 | 
						|
(b) it speeds things up for really big test cases by avoiding
 | 
						|
    interpretation of the remainder of the file.
 |