import of libc++ 6.0.0

1 files changed, 85 insertions, 19 deletions

diff --git a/lib/libcxx/docs/TestingLibcxx.rst b/lib/libcxx/docs/TestingLibcxx.rst
index 9226ae17023..43c0684dc7d 100644
--- a/lib/libcxx/docs/TestingLibcxx.rst
+++ b/lib/libcxx/docs/TestingLibcxx.rst
@@ -98,56 +98,64 @@ configuration. Passing the option on the command line will override the default.
 
 .. program:: lit
 
-.. option:: --cxx_under_test=<path/to/compiler>
+.. option:: cxx_under_test=<path/to/compiler>
 
   Specify the compiler used to build the tests.
 
+.. option:: cxx_stdlib_under_test=<stdlib name>
+
+  **Values**: libc++, libstdc++
+
+  Specify the C++ standard library being tested. Unless otherwise specified
+  libc++ is used. This option is intended to allow running the libc++ test
+  suite against other standard library implementations.
+
 .. option:: std=<standard version>
 
-  **Values**: c++98, c++03, c++11, c++14, c++1z
+  **Values**: c++98, c++03, c++11, c++14, c++17, c++2a
 
   Change the standard version used when building the tests.
 
-.. option:: --libcxx_site_config=<path/to/lit.site.cfg>
+.. option:: libcxx_site_config=<path/to/lit.site.cfg>
 
   Specify the site configuration to use when running the tests.  This option
-  overrides the enviroment variable LIBCXX_SITE_CONFIG.
+  overrides the environment variable LIBCXX_SITE_CONFIG.
 
-.. option:: --libcxx_headers=<path/to/headers>
+.. option:: cxx_headers=<path/to/headers>
 
-  Specify the libc++ headers that are tested. By default the headers in the
-  source tree are used.
+  Specify the c++ standard library headers that are tested. By default the
+  headers in the source tree are used.
 
-.. option:: --cxx_library_root=<path/to/lib/>
+.. option:: cxx_library_root=<path/to/lib/>
 
   Specify the directory of the libc++ library to be tested. By default the
   library folder of the build directory is used. This option cannot be used
-  when use_system_lib is provided.
+  when use_system_cxx_lib is provided.
 
 
-.. option:: --cxx_runtime_root=<path/to/lib/>
+.. option:: cxx_runtime_root=<path/to/lib/>
 
   Specify the directory of the libc++ library to use at runtime. This directory
   is not added to the linkers search path. This can be used to compile tests
   against one version of libc++ and run them using another. The default value
   for this option is `cxx_library_root`. This option cannot be used
-  when use_system_lib is provided.
+  when use_system_cxx_lib is provided.
 
-.. option:: --use_system_lib=<bool>
+.. option:: use_system_cxx_lib=<bool>
 
   **Default**: False
 
   Enable or disable testing against the installed version of libc++ library.
   Note: This does not use the installed headers.
 
-.. option:: --use_lit_shell=<bool>
+.. option:: use_lit_shell=<bool>
 
   Enable or disable the use of LIT's internal shell in ShTests. If the
   environment variable LIT_USE_INTERNAL_SHELL is present then that is used as
   the default value. Otherwise the default value is True on Windows and False
   on every other platform.
 
-.. option:: --no_default_flags=<bool>
+.. option:: no_default_flags=<bool>
 
   **Default**: False
 
@@ -155,16 +163,16 @@ configuration. Passing the option on the command line will override the default.
   option is used only flags specified using the compile_flags and link_flags
   will be used.
 
-.. option:: --compile_flags="<list-of-args>"
+.. option:: compile_flags="<list-of-args>"
 
   Specify additional compile flags as a space delimited string.
   Note: This options should not be used to change the standard version used.
 
-.. option:: --link_flags="<list-of-args>"
+.. option:: link_flags="<list-of-args>"
 
   Specify additional link flags as a space delimited string.
 
-.. option:: --debug_level=<level>
+.. option:: debug_level=<level>
 
   **Values**: 0, 1
 
@@ -191,10 +199,68 @@ Environment Variables
 .. envvar:: LIBCXX_SITE_CONFIG=<path/to/lit.site.cfg>
 
   Specify the site configuration to use when running the tests.
-  Also see :option:`libcxx_site_config`.
+  Also see `libcxx_site_config`.
 
 .. envvar:: LIBCXX_COLOR_DIAGNOSTICS
 
   If ``LIBCXX_COLOR_DIAGNOSTICS`` is defined then the test suite will attempt
   to use color diagnostic outputs from the compiler.
-  Also see :option:`color_diagnostics`.
+  Also see `color_diagnostics`.
+
+Benchmarks
+==========
+
+Libc++ contains benchmark tests separately from the test of the test suite.
+The benchmarks are written using the `Google Benchmark`_ library, a copy of which
+is stored in the libc++ repository.
+
+For more information about using the Google Benchmark library see the
+`official documentation <https://github.com/google/benchmark>`_.
+
+.. _`Google Benchmark`: https://github.com/google/benchmark
+
+Building Benchmarks
+-------------------
+
+The benchmark tests are not built by default. The benchmarks can be built using
+the ``cxx-benchmarks`` target.
+
+An example build would look like:
+
+.. code-block:: bash
+
+  $ cd build
+  $ cmake [options] <path to libcxx sources>
+  $ make cxx-benchmarks
+
+This will build all of the benchmarks under ``<libcxx-src>/benchmarks`` to be
+built against the just-built libc++. The compiled tests are output into
+``build/benchmarks``.
+
+The benchmarks can also be built against the platforms native standard library
+using the ``-DLIBCXX_BUILD_BENCHMARKS_NATIVE_STDLIB=ON`` CMake option. This
+is useful for comparing the performance of libc++ to other standard libraries.
+The compiled benchmarks are named ``<test>.libcxx.out`` if they test libc++ and
+``<test>.native.out`` otherwise.
+
+Also See:
+
+  * :ref:`Building Libc++ <build instructions>`
+  * :ref:`CMake Options`
+
+Running Benchmarks
+------------------
+
+The benchmarks must be run manually by the user. Currently there is no way
+to run them as part of the build.
+
+For example:
+
+.. code-block:: bash
+
+  $ cd build/benchmarks
+  $ make cxx-benchmarks
+  $ ./algorithms.libcxx.out # Runs all the benchmarks
+  $ ./algorithms.libcxx.out --benchmark_filter=BM_Sort.* # Only runs the sort benchmarks
+
+For more information about running benchmarks see `Google Benchmark`_.