[llvm] r201464 - Cleanup docs about lit substitutions

[Daniel Liew]

Thanks for doing this Nico. I reported it a while ago [1] but didn't
hear anything so I assumed it wasn't going to be fixed, but you've
proved me wrong!


[1] https://groups.google.com/forum/#!topic/llvm-dev/mWqSeV-5eGA

Thanks,
Dan.

On 15 February 2014 08:35, Nico Rieck <nico.rieck at gmail.com> wrote:
> Author: nrieck
> Date: Sat Feb 15 02:35:56 2014
> New Revision: 201464
>
> URL: http://llvm.org/viewvc/llvm-project?rev=201464&view=rev
> Log:
> Cleanup docs about lit substitutions
>
> Modified:
>     llvm/trunk/docs/TestingGuide.rst
>
> Modified: llvm/trunk/docs/TestingGuide.rst
> URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/TestingGuide.rst?rev=201464&r1=201463&r2=201464&view=diff
> ==============================================================================
> --- llvm/trunk/docs/TestingGuide.rst (original)
> +++ llvm/trunk/docs/TestingGuide.rst Sat Feb 15 02:35:56 2014
> @@ -337,69 +337,90 @@ triple, test with the specific FileCheck
>  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.
> -
> -Here are the available variable names. The alternate syntax is listed in
> -parentheses.
> -
> -``$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.
> +Besides replacing LLVM tool names the following substitutions are performed in
> +RUN lines:
>
> -``%(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.
> -
> -``$srcdir``
> -   The source directory from where the ``make check`` was run.
> -
> -``objdir``
> -   The object directory that corresponds to the ``$srcdir``.
> -
> -``subdir``
> -   A partial path from the ``test`` directory that contains the
> -   sub-directory that contains the test source being executed.
> -
> -``srcroot``
> -   The root directory of the LLVM src tree.
> -
> -``objroot``
> -   The root directory of the LLVM object tree. This could be the same as
> -   the srcroot.
> -
> -``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.
> +``%%``
> +   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.
>
> -``tmp``
> -   The path to a temporary file name that could be used for this test case.
> +   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.
>
> -``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.
> -
> -``shlibext`` (``%shlibext``)
> -   The suffix for the host platforms shared library (DLL) files. This
> -   includes the period as the first character.
> +   Example: ``/home/user/llvm.build/test/MC/ELF/Output/foo_test.s.tmp``
> +
> +``%T``
> +   Directory of ``%t``.
> +
> +   Example: ``/home/user/llvm.build/test/MC/ELF/Output``
> +
> +``%{pathsep}``
> +
> +   Expands to the path separator, i.e. ``:`` (or ``;`` on Windows).
> +
> +
> +**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.
> +
> +``%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
>  --------------
>
>
> _______________________________________________
> llvm-commits mailing list
> llvm-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits