[libc++] Allow specifying custom Lit config files
Before this patch, the libc++ test suite first loads lit.site.cfg
(generated by CMake), and then lit.cfg. It's also possible to load
lit.cfg before lit.site.cfg and to point to a custom lit.site.cfg
file using '--param=libcxx_site_config'. However, in that case, lit.cfg
still relies on the site configuration filling up the 'config' object
like the default lit.site.cfg file does, which isn't flexible enough.
This commit simplifies the setup by having just a single Lit site config
file per CMake configuration, and always loading exactly that config file.
However, the config file to use can be selected when setting up CMake via
the LIBCXX_TEST_CONFIG setting. Furthermore, the site configs are entirely
standalone, which means that a new site config can be added that doesn't
need to conform what's expected by config.py.
Differential Revision: https://reviews.llvm.org/D81846
Cr-Mirrored-From: https://chromium.googlesource.com/external/github.com/llvm/llvm-project
Cr-Mirrored-Commit: 0c66af970c806d65d9335c7272610c82c2388e31
diff --git a/docs/TestingLibcxx.rst b/docs/TestingLibcxx.rst
index 6222ef0..810131f 100644
--- a/docs/TestingLibcxx.rst
+++ b/docs/TestingLibcxx.rst
@@ -77,22 +77,18 @@
file in the build directory from the ``libcxx/test/lit.site.cfg.in`` template,
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 first, followed by the actual config in
-``libcxx/test/lit.cfg``. However, it is sometimes desirable to use a custom
-site configuration. To do that, you can use ``--param=libcxx_site_config`` or
-the ``LIBCXX_SITE_CONFIG`` environment variable to point to the right site
-configuration file. However, you must stop using ``llvm-lit``, or else the
-generated ``lit.site.cfg`` will still be preferred:
+``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
+itself to make configuration easier.
.. code-block:: bash
- $ LIBCXX_SITE_CONFIG=path/to/your/site/configuration llvm/utils/lit/lit.py -sv ...
+ $ cmake <options> -DLIBCXX_TEST_CONFIG=<path-to-site-config>
+ $ make -C <build> check-cxx-deps
+ $ <build>/bin/llvm-lit -sv libcxx/test # will use your custom config file
- $ llvm/utils/lit/lit.py -sv ... --param=libcxx_site_config=path/to/your/site/configuration
-
-In both of these cases, your custom site configuration should set up the
-``config`` object in a way that is compatible with what libc++'s ``config.py``
-module expects.
LIT Options
===========
@@ -127,11 +123,6 @@
Change the standard version used when building the tests.
-.. option:: libcxx_site_config=<path/to/lit.site.cfg>
-
- Specify the site configuration to use when running the tests. This option
- overrides the environment variable LIBCXX_SITE_CONFIG.
-
.. option:: cxx_headers=<path/to/headers>
Specify the c++ standard library headers that are tested. By default the
@@ -199,14 +190,6 @@
Path to the builtins library to use instead of libgcc.
-Environment Variables
----------------------
-
-.. envvar:: LIBCXX_SITE_CONFIG=<path/to/lit.site.cfg>
-
- Specify the site configuration to use when running the tests.
- Also see `libcxx_site_config`.
-
Writing Tests
-------------