From 4b3ec1763c22130fb91380413a8c3ddbdf044c3e Mon Sep 17 00:00:00 2001 From: Nico Rieck Date: Sat, 15 Feb 2014 08:35:56 +0000 Subject: Cleanup docs about lit substitutions git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@201464 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/TestingGuide.rst | 117 +++++++++++++++++++++++++++++--------------------- 1 file changed, 69 insertions(+), 48 deletions(-) (limited to 'docs') 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+)``, ``%(line-)`` - 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+)``, ``%(line-)`` + 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 -------------- -- cgit v1.2.3