[lit] Document the 'target=<triple>' feature

[probinson]

Summary

Apparently I forgot to do this when making the lit change in
https://github.com/llvm/llvm-project/commit/56470b72f1fc1727d5ee87e2fed96e7dad286230

[probinson]

Also update examples.

[probinson]

I've just discovered there's a compiler-rt version of this file that also talks about triple substrings. I'll get to that in a bit.

compiler-rt/docs/TestingGuide.rst

 out in the directory ``llvm/projects/compiler-rt/test``. Use ``make check-all``
 to run the regression tests after building compiler-rt.
 
 REQUIRES, XFAIL, etc.
 ---------------------
 
 Sometimes it is necessary to restrict a test to a specific target or mark it as
 an "expected fail" or XFAIL. This is normally achieved using ``REQUIRES:`` or
-``XFAIL:`` with a substring of LLVM's default target triple. Unfortunately, the
+``XFAIL:`` and the ``target=<target-triple>`` feature, typically with a regular
+expression matching an appropriate substring of the triple. Unfortunately, the
 behaviour of this is somewhat quirky in compiler-rt. There are two main
 pitfalls to avoid.
 
-The first pitfall is that these directives perform a substring match on the
-triple and as such ``XFAIL: mips`` affects more triples than expected. For
-example, ``mips-linux-gnu``, ``mipsel-linux-gnu``, ``mips64-linux-gnu``, and
-``mips64el-linux-gnu`` will all match a ``XFAIL: mips`` directive. Including a
-trailing ``-`` such as in ``XFAIL: mips-`` can help to mitigate this quirk but
-even that has issues as described below.
+The first pitfall is that these regular expressions may inadvertently match
+more triples than expected. For example, ``XFAIL: target=mips{{.*}}`` matches
+``mips-linux-gnu``, ``mipsel-linux-gnu``, ``mips64-linux-gnu``, and
+``mips64el-linux-gnu``. Including a trailing ``-`` such as in 
+``XFAIL: target=mips-{{.*}}`` can help to mitigate this quirk but even that has
+issues as described below.
 
 The second pitfall is that the default target triple is often inappropriate for
 compiler-rt tests since compiler-rt tests may be compiled for multiple targets.
 For example, a typical build on an ``x86_64-linux-gnu`` host will often run the
-tests for both x86_64 and i386. In this situation ``XFAIL: x86_64`` will mark
-both the x86_64 and i386 tests as an expected failure while ``XFAIL: i386``
-will have no effect at all.
+tests for both x86_64 and i386. In this situation ``XFAIL: target=x86_64{{{.*}}``
+will mark both the x86_64 and i386 tests as an expected failure while 
+``XFAIL: target=i386{{.*}}`` will have no effect at all.
 
 To remedy both pitfalls, compiler-rt tests provide a feature string which can
 be used to specify a single target. This string is of the form
 ``target-is-${arch}`` where ``${arch}}`` is one of the values from the
 following lines of the CMake output::
 
   -- Compiler-RT supported architectures: x86_64;i386
   -- Builtin supported architectures: i386;x86_64
 
 So for example ``XFAIL: target-is-x86_64`` will mark a test as expected to fail
 on x86_64 without also affecting the i386 test and ``XFAIL: target-is-i386``
 will mark a test as expected to fail on i386 even if the default target triple
 is ``x86_64-linux-gnu``. Directives that use these ``target-is-${arch}`` string
 require exact matches so ``XFAIL: target-is-mips``,
 ``XFAIL: target-is-mipsel``, ``XFAIL: target-is-mips64``, and
 ``XFAIL: target-is-mips64el`` all refer to different MIPS targets.

llvm/docs/TestingGuide.rst

 that the test detect. Use ``XFAIL`` to mark a test as an expected failure.
 An ``XFAIL`` test will be successful if its execution fails, and
 will be a failure if its execution succeeds.
 
 .. code-block:: llvm
 
     ; This test will be only enabled in the build with asserts.
     ; REQUIRES: asserts
-    ; This test is disabled on Linux.
-    ; UNSUPPORTED: -linux-
-    ; This test is expected to fail on PowerPC.
-    ; XFAIL: powerpc
+    ; This test is disabled when running on Linux.
+    ; UNSUPPORTED: system-linux
+    ; This test is expected to fail when targeting PowerPC.
+    ; XFAIL: target=powerpc{{.*}}
 
 ``REQUIRES`` and ``UNSUPPORTED`` and ``XFAIL`` all accept a comma-separated
 list of boolean expressions. The values in each expression may be:
 
 - Features added to ``config.available_features`` by configuration files such as ``lit.cfg``.
   String comparison of features is case-sensitive. Furthermore, a boolean expression can
   contain any Python regular expression enclosed in ``{{ }}``, in which case the boolean
   expression is satisfied if any feature matches the regular expression. Regular
   expressions can appear inside an identifier, so for example ``he{{l+}}o`` would match
   ``helo``, ``hello``, ``helllo``, and so on.
-- Substrings of the target triple (``UNSUPPORTED`` and ``XFAIL`` only).
+- The default target triple, preceded by the string ``target=`` (for example,
+  ``target=x86_64-pc-windows-msvc``). Typically regular expressions are used
+  to match parts of the triple (for example, ``target={{.*}}-windows{{.*}}``
+  to match any Windows target triple).
 
 | ``REQUIRES`` enables the test if all expressions are true.
 | ``UNSUPPORTED`` disables the test if any expression is true.
 | ``XFAIL`` expects the test to fail if any expression is true.
 
 As a special case, ``XFAIL: *`` is expected to fail everywhere.
 
 .. code-block:: llvm
 
-    ; This test is disabled on Windows,
-    ; and is disabled on Linux, except for Android Linux.
-    ; UNSUPPORTED: windows, linux && !android
-    ; This test is expected to fail on both PowerPC and ARM.
-    ; XFAIL: powerpc || arm
+    ; This test is disabled when running on Windows,
+    ; and is disabled when targeting Linux, except for Android Linux.
+    ; UNSUPPORTED: system-windows, target={{.*linux.*}} && !target={{.*android.*}}
+    ; This test is expected to fail when targeting PowerPC or running on Darwin.
+    ; XFAIL: target=powerpc{{.*}}, system-darwin
 
 
 Substitutions
 -------------
 
 Besides replacing LLVM tool names the following substitutions are performed in
 RUN lines: