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

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

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
 ----------------

libcxx/utils/libcxx-lit

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+
+set -e
+
+PROGNAME="$(basename "${0}")"
+function usage() {
+cat <<EOF
+Usage:
+${PROGNAME} [-h|--help] <build-directory> [lit options...] tests...
+
+Shortcut to build the libc++ testing dependencies and run the libc++ tests with Lit.
+
+<build-directory>  The path to the build directory to use for building the library.
+[lit options...]   Optional options to pass to 'llvm-lit'.
+tests...           Paths of the tests to run. Those are paths relative to '<monorepo-root>/libcxx/test'.
+
+Example
+=======
+$ cmake -S runtimes -B build/ -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi"
+$ libcxx-lit build/ -sv libcxx/test/std/utilities/
+EOF
+}
+
+for arg in $@; do
+    if [[ "${arg}" == "-h" || "${arg}" == "--help" ]]; then
+        usage
+        exit 0
+    fi
+done
+
+if [[ $# -lt 1 ]]; then
+    usage
+    exit 1
+fi
+
+build_dir="${1}"
+shift
+
+cmake --build "${build_dir}" --target cxx-test-depends
+"${build_dir}/bin/llvm-lit" ${@}