[docs] Add tips on writing test constraints

[probinson]

Summary

Guidance on using REQUIRES, UNSUPPORTED, XFAIL, and the target=... feature.

Things I thought of while updating lots and lots of lit tests.

[ldionne]

Thanks for writing this! This LGTM but I would suggest dumbing down your target example even more.

llvm/docs/TestingGuide.rst

571–573

I might even suggest doing target={{.+}}-freebsd-{{.+}} || target={{.+}}-netbsd-{{.+}}. Characters are cheap and IMO this is clearer than trying to cram more logic into something smaller.

[probinson]

llvm/docs/TestingGuide.rst

571–573

Oh, didn't see this comment before I pushed. Yeah... separating them entirely might be a better example.
I'm still inclined to use freebsd{{.*}} though, because there isn't guaranteed to be a -suffix and there might be a version number (I remember seeing -freebsd9 years ago).

[probinson]

Example updated.

[ldionne]

This landed as 2549b8bdae67ab8c1a6ecd974b17b3e3413ae622, closing to clear the review queue.

llvm/docs/TestingGuide.rst

.. code-block:: llvm
 
     ; 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
 
 
+Tips for writing constraints
+----------------------------
+
+**``REQUIRES`` and ``UNSUPPORTED``**
+
+These are logical inverses. In principle, ``UNSUPPORTED`` isn't absolutely
+necessary (the logical negation could be used with ``REQUIRES`` to get
+exactly the same effect), but it can make these clauses easier to read and
+understand. Generally, people use ``REQUIRES`` to state things that the test
+depends on to operate correctly, and ``UNSUPPORTED`` to exclude cases where
+the test is expected never to work.
+
+**``UNSUPPORTED`` and ``XFAIL``**
+
+Both of these indicate that the test isn't expected to work; however, they
+have different effects. ``UNSUPPORTED`` causes the test to be skipped;
+this saves execution time, but then you'll never know whether the test
+actually would start working. Conversely, ``XFAIL`` actually runs the test
+but expects a failure output, taking extra execution time but alerting you
+if/when the test begins to behave correctly (an XPASS test result). You
+need to decide which is more appropriate in each case.
+
+**Using ``target=...``**
+
+Checking the target triple can be tricky; it's easy to mis-specify. For
+example, ``target=mips{{.*}}`` will match not only mips, but also mipsel,
+mips64, and mips64el. ``target={{.*}}-linux-gnu`` will match
+x86_64-unknown-linux-gnu, but not armv8l-unknown-linux-gnueabihf.
+Prefer to use hyphens to delimit triple components (``target=mips-{{.*}}``)
+and it's generally a good idea to use a trailing wildcard to allow for
+unexpected suffixes.
+
+Also, it's generally better to write regular expressions that use entire
+triple components, than to do something clever to shorten them. For
+example, to match both freebsd and netbsd in an expression, you could write
+``target={{.*(free|net)bsd.*}}`` and that would work. However, it would
+prevent a ``grep freebsd`` from finding this test. Better to use 
+``target={{.*(freebsd|netbsd).*}}`` in this case.
+
+
 Substitutions
 -------------
 
 Besides replacing LLVM tool names the following substitutions are performed in
 RUN lines:
 
 ``%%``
    Replaced by a single ``%``. This allows escaping other substitutions.