diff options
| author | Stephen Hines <srhines@google.com> | 2014-04-23 16:57:46 -0700 |
|---|---|---|
| committer | Stephen Hines <srhines@google.com> | 2014-04-24 15:53:16 -0700 |
| commit | 36b56886974eae4f9c5ebc96befd3e7bfe5de338 (patch) | |
| tree | e6cfb69fbbd937f450eeb83bfb83b9da3b01275a /docs/TestingGuide.rst | |
| parent | 69a8640022b04415ae9fac62f8ab090601d8f889 (diff) | |
| download | external_llvm-36b56886974eae4f9c5ebc96befd3e7bfe5de338.zip external_llvm-36b56886974eae4f9c5ebc96befd3e7bfe5de338.tar.gz external_llvm-36b56886974eae4f9c5ebc96befd3e7bfe5de338.tar.bz2 | |
Update to LLVM 3.5a.
Change-Id: Ifadecab779f128e62e430c2b4f6ddd84953ed617
Diffstat (limited to 'docs/TestingGuide.rst')
| -rw-r--r-- | docs/TestingGuide.rst | 135 |
1 files changed, 74 insertions, 61 deletions
diff --git a/docs/TestingGuide.rst b/docs/TestingGuide.rst index c9a35cd..f9222372 100644 --- a/docs/TestingGuide.rst +++ b/docs/TestingGuide.rst @@ -337,87 +337,100 @@ 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`` -``$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 |