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.4 or later.
+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.5 or
+later.
LLVM testing infrastructure organization
========================================
directory that will filter out all other architectures.
-Variables and substitutions
----------------------------
+Substitutions
+-------------
-With a RUN line there are a number of substitutions that are permitted.
-To make a substitution just write the variable's name preceded by a ``$``.
-Additionally, for compatibility reasons with previous versions of the
-test library, certain names can be accessed with an alternate syntax: a
-% prefix. These alternates are deprecated and may go away in a future
-version.
+Besides replacing LLVM tool names the following substitutions are performed in
+RUN lines:
-Here are the available variable names. The alternate syntax is listed in
-parentheses.
+``%%``
+ Replaced by a single ``%``. This allows escaping other substitutions.
-``$test`` (``%s``)
- The full path to the test case's source. This is suitable for passing on
- the command line as the input to an LLVM tool.
+``%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.
-``%(line)``, ``%(line+<number>)``, ``%(line-<number>)``
- The number of the line where this variable is used, with an optional
- integer offset. This can be used in tests with multiple RUN lines,
- which reference test file's line numbers.
+ Example: ``/home/user/llvm/test/MC/ELF/foo_test.s``
-``$srcdir``
- The source directory from where the ``make check`` was run.
+``%S``
+ Directory path to the test case's source.
-``objdir``
- The object directory that corresponds to the ``$srcdir``.
+ Example: ``/home/user/llvm/test/MC/ELF``
-``subdir``
- A partial path from the ``test`` directory that contains the
- sub-directory that contains the test source being executed.
+``%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.
-``srcroot``
- The root directory of the LLVM src tree.
+ Example: ``/home/user/llvm.build/test/MC/ELF/Output/foo_test.s.tmp``
-``objroot``
- The root directory of the LLVM object tree. This could be the same as
- the srcroot.
+``%T``
+ Directory of ``%t``.
-``path``
- The path to the directory that contains the test case source. This is
- for locating any supporting files that are not generated by the test,
- but used by the test.
+ Example: ``/home/user/llvm.build/test/MC/ELF/Output``
-``tmp``
- The 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.
+``%{pathsep}``
+
+ Expands to the path separator, i.e. ``:`` (or ``;`` on Windows).
-``target_triplet`` (``%target_triplet``)
- The target triplet that corresponds to the current host machine (the one
- running the test cases). This should probably be called "host".
-``link`` (``%link``)
- This full link command used to link LLVM executables. This has all the
- configured ``-I``, ``-L`` and ``-l`` options.
+**LLVM-specific substitutions:**
-``shlibext`` (``%shlibext``)
- The suffix for the host platforms shared library (DLL) files. This
- includes the period as the first character.
+``%shlibext``
+ The suffix for the host platforms shared library files. This includes the
+ period as the first character.
+
+ Example: ``.so`` (Linux), ``.dylib`` (OS X), ``.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.
+
+To add more substituations, look at ``test/lit.cfg`` or ``lit.local.cfg``.
-To add more variables, look at ``test/lit.cfg``.
Other Features
--------------
-To make RUN line writing easier, there are several helper scripts and programs
-in the ``llvm/test/Scripts`` directory. This directory is in the PATH
-when running tests, so you can just call these scripts using their name.
-For example:
-
-``ignore``
- This script runs its arguments and then always returns 0. This is useful
- in cases where the test needs to cause a tool to generate an error (e.g.
- to check the error output). However, any program in a pipeline that
- returns a non-zero result will cause the test to fail. This script
- overcomes that issue and nicely documents that the test case is
- purposefully ignoring the result code of the tool
+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 script runs its arguments and then inverts the result code from it.
+ This program runs its arguments and then inverts the result code from it.
Zero result codes become 1. Non-zero result codes become 0.
Sometimes it is necessary to mark a test case as "expected fail" or
projects / oota-llvm.git / blobdiff