[libc++] Add helper script libcxx-lit for running tests

Differential Revision: https://reviews.llvm.org/D148632

1 files changed, 14 insertions, 8 deletions

diff --git a/libcxx/docs/TestingLibcxx.rst b/libcxx/docs/TestingLibcxx.rst
index 9a69000e8237..9dc8792f5a78 100644
--- a/libcxx/docs/TestingLibcxx.rst
+++ b/libcxx/docs/TestingLibcxx.rst
@@ -49,7 +49,14 @@ In the default configuration, the tests are built against headers that form a
 fake installation root of libc++. This installation root has to be updated when
 changes are made to the headers, so you should re-run the ``cxx-test-depends``
 target before running the tests manually with ``lit`` when you make any sort of
-change, including to the headers.
+change, including to the headers. We recommend using the provided ``libcxx/utils/libcxx-lit``
+script to automate this so you don't have to think about building test dependencies
+every time:
+
+.. code-block:: bash
+
+  $ cd <monorepo-root>
+  $ libcxx/utils/libcxx-lit <build> -sv libcxx/test/std/re # Build testing dependencies and run all of the std::regex tests
 
 Sometimes you'll want to change the way LIT is running the tests. Custom options
 can be specified using the ``--param <name>=<val>`` flag. The most common option
@@ -59,8 +66,8 @@ that. However, you can manually specify the option like so if you want:
 
 .. code-block:: bash
 
-  $ <build>/bin/llvm-lit -sv libcxx/test/std/containers # Run the tests with the newest -std
-  $ <build>/bin/llvm-lit -sv libcxx/test/std/containers --param std=c++03 # Run the tests in C++03
+  $ libcxx/utils/libcxx-lit <build> -sv libcxx/test/std/containers # Run the tests with the newest -std
+  $ libcxx/utils/libcxx-lit <build> -sv libcxx/test/std/containers --param std=c++03 # Run the tests in C++03
 
 Other parameters are supported by the test suite. Those are defined in ``libcxx/utils/libcxx/test/params.py``.
 If you want to customize how to run the libc++ test suite beyond what is available
@@ -81,9 +88,9 @@ the current CMake configuration. It does so by generating a ``lit.site.cfg``
 file in the build directory from one of the configuration file templates in
 ``libcxx/test/configs/``, and pointing ``llvm-lit`` (which is a wrapper around
 ``llvm/utils/lit/lit.py``) to that file. So when you're running
-``<build>/bin/llvm-lit``, the generated ``lit.site.cfg`` file is always loaded
-instead of ``libcxx/test/lit.cfg.py``. If you want to use a custom site
-configuration, simply point the CMake build to it using
+``<build>/bin/llvm-lit`` either directly or indirectly, the generated ``lit.site.cfg``
+file is always loaded instead of ``libcxx/test/lit.cfg.py``. If you want to use a
+custom site configuration, simply point the CMake build to it using
 ``-DLIBCXX_TEST_CONFIG=<path-to-site-config>``, and that site configuration
 will be used instead. That file can use CMake variables inside it to make
 configuration easier.
@@ -91,8 +98,7 @@ configuration easier.
    .. code-block:: bash
 
      $ cmake <options> -DLIBCXX_TEST_CONFIG=<path-to-site-config>
-     $ make -C <build> cxx-test-depends
-     $ <build>/bin/llvm-lit -sv libcxx/test # will use your custom config file
+     $ libcxx/utils/libcxx-lit <build> -sv libcxx/test # will use your custom config file
 
 Additional tools
 ----------------