Cleanup docs about lit substitutions

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@201464 91177308-0d34-0410-b5e6-96231b3b80d8

1 files changed, 69 insertions, 48 deletions

diff --git a/docs/TestingGuide.rst b/docs/TestingGuide.rst
index eb61bdfc2c..f9222372c2 100644
--- a/docs/TestingGuide.rst
+++ b/docs/TestingGuide.rst
@@ -337,69 +337,90 @@ triple, test with the specific FileCheck and put it into the specific
 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``
+
+``%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.
 
-``$srcdir``
-   The source directory from where the ``make check`` was run.
+   Example: ``/home/user/llvm.build/test/MC/ELF/Output/foo_test.s.tmp``
 
-``objdir``
-   The object directory that corresponds to the ``$srcdir``.
+``%T``
+   Directory of ``%t``.
 
-``subdir``
-   A partial path from the ``test`` directory that contains the
-   sub-directory that contains the test source being executed.
+   Example: ``/home/user/llvm.build/test/MC/ELF/Output``
 
-``srcroot``
-   The root directory of the LLVM src tree.
+``%{pathsep}``
 
-``objroot``
-   The root directory of the LLVM object tree. This could be the same as
-   the srcroot.
+   Expands to the path separator, i.e. ``:`` (or ``;`` on Windows).
 
-``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.
 
-``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.
+**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`` (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.
 
-``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".
+``%clang_cc1``
+   Invokes the Clang frontend.
 
-``link`` (``%link``)
-   This full link command used to link LLVM executables. This has all the
-   configured ``-I``, ``-L`` and ``-l`` options.
+``%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.
 
-``shlibext`` (``%shlibext``)
-   The suffix for the host platforms shared library (DLL) files. This
-   includes the period as the first character.
+To add more substituations, look at ``test/lit.cfg`` or ``lit.local.cfg``.
 
-To add more variables, look at ``test/lit.cfg``.
 
 Other Features
 --------------