2015-08-23 03:40:49 +08:00
|
|
|
==============
|
|
|
|
Testing libc++
|
|
|
|
==============
|
|
|
|
|
|
|
|
.. contents::
|
|
|
|
:local:
|
|
|
|
|
|
|
|
Getting Started
|
|
|
|
===============
|
|
|
|
|
|
|
|
libc++ uses LIT to configure and run its tests. The primary way to run the
|
|
|
|
libc++ tests is by using make check-libcxx. However since libc++ can be used
|
|
|
|
in any number of possible configurations it is important to customize the way
|
|
|
|
LIT builds and runs the tests. This guide provides information on how to use
|
|
|
|
LIT directly to test libc++.
|
|
|
|
|
|
|
|
Please see the `Lit Command Guide`_ for more information about LIT.
|
|
|
|
|
|
|
|
.. _LIT Command Guide: http://llvm.org/docs/CommandGuide/lit.html
|
|
|
|
|
|
|
|
Setting up the Environment
|
|
|
|
--------------------------
|
|
|
|
|
|
|
|
After building libc++ you must setup your environment to test libc++ using
|
|
|
|
LIT.
|
|
|
|
|
|
|
|
#. Create a shortcut to the actual lit executable so that you can invoke it
|
|
|
|
easily from the command line.
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ alias lit='python path/to/llvm/utils/lit/lit.py'
|
|
|
|
|
|
|
|
#. Tell LIT where to find your build configuration.
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ export LIBCXX_SITE_CONFIG=path/to/build-libcxx/test/lit.site.cfg
|
|
|
|
|
2015-10-15 04:44:44 +08:00
|
|
|
Example Usage
|
|
|
|
-------------
|
|
|
|
|
|
|
|
Once you have your environment set up and you have built libc++ you can run
|
|
|
|
parts of the libc++ test suite by simply running `lit` on a specified test or
|
|
|
|
directory. For example:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ cd path/to/src/libcxx
|
|
|
|
$ lit -sv test/std/re # Run all of the std::regex tests
|
|
|
|
$ lit -sv test/std/depr/depr.c.headers/stdlib_h.pass.cpp # Run a single test
|
|
|
|
$ lit -sv test/std/atomics test/std/threads # Test std::thread and std::atomic
|
|
|
|
|
|
|
|
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
|
|
|
|
you'll want to change is the standard dialect (ie -std=c++XX). By default the
|
|
|
|
test suite will select the newest C++ dialect supported by the compiler and use
|
|
|
|
that. However if you want to manually specify the option like so:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ lit -sv test/std/containers # Run the tests with the newest -std
|
|
|
|
$ lit -sv --param=std=c++03 test/std/containers # Run the tests in C++03
|
|
|
|
|
|
|
|
Occasionally you'll want to add extra compile or link flags when testing.
|
|
|
|
You can do this as follows:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ lit -sv --param=compile_flags='-Wcustom-warning'
|
|
|
|
$ lit -sv --param=link_flags='-L/custom/library/path'
|
|
|
|
|
|
|
|
Some other common examples include:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
# Specify a custom compiler.
|
|
|
|
$ lit -sv --param=cxx_under_test=/opt/bin/g++ test/std
|
|
|
|
|
|
|
|
# Enable warnings in the test suite
|
|
|
|
$ lit -sv --param=enable_warnings=true test/std
|
|
|
|
|
|
|
|
# Use UBSAN when running the tests.
|
|
|
|
$ lit -sv --param=use_sanitizer=Undefined
|
|
|
|
|
2015-08-23 03:40:49 +08:00
|
|
|
|
|
|
|
LIT Options
|
|
|
|
===========
|
|
|
|
|
|
|
|
:program:`lit` [*options*...] [*filenames*...]
|
|
|
|
|
|
|
|
Command Line Options
|
|
|
|
--------------------
|
|
|
|
|
|
|
|
To use these options you pass them on the LIT command line as --param NAME or
|
|
|
|
--param NAME=VALUE. Some options have default values specified during CMake's
|
|
|
|
configuration. Passing the option on the command line will override the default.
|
|
|
|
|
|
|
|
.. program:: lit
|
|
|
|
|
2016-10-14 14:15:27 +08:00
|
|
|
.. option:: cxx_under_test=<path/to/compiler>
|
2015-10-15 04:44:44 +08:00
|
|
|
|
|
|
|
Specify the compiler used to build the tests.
|
|
|
|
|
2016-10-14 14:15:27 +08:00
|
|
|
.. option:: cxx_stdlib_under_test=<stdlib name>
|
|
|
|
|
|
|
|
**Values**: libc++, libstdc++
|
2016-10-12 08:00:37 +08:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2015-10-15 04:44:44 +08:00
|
|
|
.. option:: std=<standard version>
|
|
|
|
|
2017-11-08 04:26:23 +08:00
|
|
|
**Values**: c++98, c++03, c++11, c++14, c++17, c++2a
|
2015-10-15 04:44:44 +08:00
|
|
|
|
|
|
|
Change the standard version used when building the tests.
|
|
|
|
|
2016-10-14 14:15:27 +08:00
|
|
|
.. option:: libcxx_site_config=<path/to/lit.site.cfg>
|
2015-08-23 03:40:49 +08:00
|
|
|
|
|
|
|
Specify the site configuration to use when running the tests. This option
|
2017-05-10 07:47:20 +08:00
|
|
|
overrides the environment variable LIBCXX_SITE_CONFIG.
|
2015-08-23 03:40:49 +08:00
|
|
|
|
2016-10-14 14:15:27 +08:00
|
|
|
.. option:: cxx_headers=<path/to/headers>
|
2015-08-23 03:40:49 +08:00
|
|
|
|
2016-10-12 08:00:37 +08:00
|
|
|
Specify the c++ standard library headers that are tested. By default the
|
|
|
|
headers in the source tree are used.
|
2015-08-23 03:40:49 +08:00
|
|
|
|
2016-10-14 14:15:27 +08:00
|
|
|
.. option:: cxx_library_root=<path/to/lib/>
|
2015-08-23 03:40:49 +08:00
|
|
|
|
2016-04-20 12:17:39 +08:00
|
|
|
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
|
2016-12-24 03:09:14 +08:00
|
|
|
when use_system_cxx_lib is provided.
|
2016-04-20 12:17:39 +08:00
|
|
|
|
|
|
|
|
2016-10-14 14:15:27 +08:00
|
|
|
.. option:: cxx_runtime_root=<path/to/lib/>
|
2016-04-20 12:17:39 +08:00
|
|
|
|
|
|
|
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
|
2018-12-15 02:19:14 +08:00
|
|
|
for this option is `cxx_library_root`.
|
2015-08-23 03:40:49 +08:00
|
|
|
|
2016-12-24 03:09:14 +08:00
|
|
|
.. option:: use_system_cxx_lib=<bool>
|
2015-08-23 03:40:49 +08:00
|
|
|
|
|
|
|
**Default**: False
|
|
|
|
|
|
|
|
Enable or disable testing against the installed version of libc++ library.
|
|
|
|
Note: This does not use the installed headers.
|
|
|
|
|
2016-10-14 14:15:27 +08:00
|
|
|
.. option:: use_lit_shell=<bool>
|
2015-08-23 03:40:49 +08:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2016-10-14 14:15:27 +08:00
|
|
|
.. option:: compile_flags="<list-of-args>"
|
2015-08-23 03:40:49 +08:00
|
|
|
|
|
|
|
Specify additional compile flags as a space delimited string.
|
|
|
|
Note: This options should not be used to change the standard version used.
|
|
|
|
|
2016-10-14 14:15:27 +08:00
|
|
|
.. option:: link_flags="<list-of-args>"
|
2015-08-23 03:40:49 +08:00
|
|
|
|
|
|
|
Specify additional link flags as a space delimited string.
|
|
|
|
|
2016-10-14 14:15:27 +08:00
|
|
|
.. option:: debug_level=<level>
|
2015-08-23 03:40:49 +08:00
|
|
|
|
|
|
|
**Values**: 0, 1
|
|
|
|
|
|
|
|
Enable the use of debug mode. Level 0 enables assertions and level 1 enables
|
|
|
|
assertions and debugging of iterator misuse.
|
|
|
|
|
|
|
|
.. option:: use_sanitizer=<sanitizer name>
|
|
|
|
|
|
|
|
**Values**: Memory, MemoryWithOrigins, Address, Undefined
|
|
|
|
|
|
|
|
Run the tests using the given sanitizer. If LLVM_USE_SANITIZER was given when
|
|
|
|
building libc++ then that sanitizer will be used by default.
|
|
|
|
|
|
|
|
.. option:: color_diagnostics
|
|
|
|
|
|
|
|
Enable the use of colorized compile diagnostics. If the color_diagnostics
|
|
|
|
option is specified or the environment variable LIBCXX_COLOR_DIAGNOSTICS is
|
|
|
|
present then color diagnostics will be enabled.
|
|
|
|
|
2019-02-06 03:50:47 +08:00
|
|
|
.. option:: llvm_unwinder
|
|
|
|
|
|
|
|
Enable the use of LLVM unwinder instead of libgcc.
|
|
|
|
|
|
|
|
.. option:: builtins_library
|
|
|
|
|
|
|
|
Path to the builtins library to use instead of libgcc.
|
|
|
|
|
2015-08-23 03:40:49 +08:00
|
|
|
|
|
|
|
Environment Variables
|
|
|
|
---------------------
|
|
|
|
|
2016-05-05 16:12:25 +08:00
|
|
|
.. envvar:: LIBCXX_SITE_CONFIG=<path/to/lit.site.cfg>
|
2015-08-23 03:40:49 +08:00
|
|
|
|
|
|
|
Specify the site configuration to use when running the tests.
|
2016-09-16 11:47:53 +08:00
|
|
|
Also see `libcxx_site_config`.
|
2015-08-23 03:40:49 +08:00
|
|
|
|
|
|
|
.. envvar:: LIBCXX_COLOR_DIAGNOSTICS
|
|
|
|
|
|
|
|
If ``LIBCXX_COLOR_DIAGNOSTICS`` is defined then the test suite will attempt
|
|
|
|
to use color diagnostic outputs from the compiler.
|
2016-09-16 11:47:53 +08:00
|
|
|
Also see `color_diagnostics`.
|
[libcxx] Add support for benchmark tests using Google Benchmark.
Summary:
This patch does the following:
1. Checks in a copy of the Google Benchmark library into the libc++ repo under `utils/google-benchmark`.
2. Teaches libc++ how to build Google Benchmark against both (A) in-tree libc++ and (B) the platforms native STL.
3. Allows performance benchmarks to be built as part of the libc++ build.
Building the benchmarks (and Google Benchmark) is off by default. It must be enabled using the CMake option `-DLIBCXX_INCLUDE_BENCHMARKS=ON`. When this option is enabled the tests under `libcxx/benchmarks` can be built using the `libcxx-benchmarks` target.
On Linux platforms where libstdc++ is the default STL the CMake option `-DLIBCXX_BUILD_BENCHMARKS_NATIVE_STDLIB=ON` can be used to build each benchmark test against libstdc++ as well. This is useful for comparing performance between standard libraries.
Support for benchmarks is currently very minimal. They must be manually run by the user and there is no mechanism for detecting performance regressions.
Known Issues:
* `-DLIBCXX_INCLUDE_BENCHMARKS=ON` is only supported for Clang, and not GCC, since the `-stdlib=libc++` option is needed to build Google Benchmark.
Reviewers: danalbert, dberlin, chandlerc, mclow.lists, jroelofs
Subscribers: chandlerc, dberlin, tberghammer, danalbert, srhines, hfinkel
Differential Revision: https://reviews.llvm.org/D22240
llvm-svn: 276049
2016-07-20 07:07:03 +08:00
|
|
|
|
|
|
|
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
|
|
|
|
-------------------
|
|
|
|
|
2016-08-30 03:50:49 +08:00
|
|
|
The benchmark tests are not built by default. The benchmarks can be built using
|
|
|
|
the ``cxx-benchmarks`` target.
|
[libcxx] Add support for benchmark tests using Google Benchmark.
Summary:
This patch does the following:
1. Checks in a copy of the Google Benchmark library into the libc++ repo under `utils/google-benchmark`.
2. Teaches libc++ how to build Google Benchmark against both (A) in-tree libc++ and (B) the platforms native STL.
3. Allows performance benchmarks to be built as part of the libc++ build.
Building the benchmarks (and Google Benchmark) is off by default. It must be enabled using the CMake option `-DLIBCXX_INCLUDE_BENCHMARKS=ON`. When this option is enabled the tests under `libcxx/benchmarks` can be built using the `libcxx-benchmarks` target.
On Linux platforms where libstdc++ is the default STL the CMake option `-DLIBCXX_BUILD_BENCHMARKS_NATIVE_STDLIB=ON` can be used to build each benchmark test against libstdc++ as well. This is useful for comparing performance between standard libraries.
Support for benchmarks is currently very minimal. They must be manually run by the user and there is no mechanism for detecting performance regressions.
Known Issues:
* `-DLIBCXX_INCLUDE_BENCHMARKS=ON` is only supported for Clang, and not GCC, since the `-stdlib=libc++` option is needed to build Google Benchmark.
Reviewers: danalbert, dberlin, chandlerc, mclow.lists, jroelofs
Subscribers: chandlerc, dberlin, tberghammer, danalbert, srhines, hfinkel
Differential Revision: https://reviews.llvm.org/D22240
llvm-svn: 276049
2016-07-20 07:07:03 +08:00
|
|
|
|
|
|
|
An example build would look like:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ cd build
|
2016-08-30 03:50:49 +08:00
|
|
|
$ cmake [options] <path to libcxx sources>
|
|
|
|
$ make cxx-benchmarks
|
[libcxx] Add support for benchmark tests using Google Benchmark.
Summary:
This patch does the following:
1. Checks in a copy of the Google Benchmark library into the libc++ repo under `utils/google-benchmark`.
2. Teaches libc++ how to build Google Benchmark against both (A) in-tree libc++ and (B) the platforms native STL.
3. Allows performance benchmarks to be built as part of the libc++ build.
Building the benchmarks (and Google Benchmark) is off by default. It must be enabled using the CMake option `-DLIBCXX_INCLUDE_BENCHMARKS=ON`. When this option is enabled the tests under `libcxx/benchmarks` can be built using the `libcxx-benchmarks` target.
On Linux platforms where libstdc++ is the default STL the CMake option `-DLIBCXX_BUILD_BENCHMARKS_NATIVE_STDLIB=ON` can be used to build each benchmark test against libstdc++ as well. This is useful for comparing performance between standard libraries.
Support for benchmarks is currently very minimal. They must be manually run by the user and there is no mechanism for detecting performance regressions.
Known Issues:
* `-DLIBCXX_INCLUDE_BENCHMARKS=ON` is only supported for Clang, and not GCC, since the `-stdlib=libc++` option is needed to build Google Benchmark.
Reviewers: danalbert, dberlin, chandlerc, mclow.lists, jroelofs
Subscribers: chandlerc, dberlin, tberghammer, danalbert, srhines, hfinkel
Differential Revision: https://reviews.llvm.org/D22240
llvm-svn: 276049
2016-07-20 07:07:03 +08:00
|
|
|
|
|
|
|
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
|
2016-08-30 03:50:49 +08:00
|
|
|
$ make cxx-benchmarks
|
[libcxx] Add support for benchmark tests using Google Benchmark.
Summary:
This patch does the following:
1. Checks in a copy of the Google Benchmark library into the libc++ repo under `utils/google-benchmark`.
2. Teaches libc++ how to build Google Benchmark against both (A) in-tree libc++ and (B) the platforms native STL.
3. Allows performance benchmarks to be built as part of the libc++ build.
Building the benchmarks (and Google Benchmark) is off by default. It must be enabled using the CMake option `-DLIBCXX_INCLUDE_BENCHMARKS=ON`. When this option is enabled the tests under `libcxx/benchmarks` can be built using the `libcxx-benchmarks` target.
On Linux platforms where libstdc++ is the default STL the CMake option `-DLIBCXX_BUILD_BENCHMARKS_NATIVE_STDLIB=ON` can be used to build each benchmark test against libstdc++ as well. This is useful for comparing performance between standard libraries.
Support for benchmarks is currently very minimal. They must be manually run by the user and there is no mechanism for detecting performance regressions.
Known Issues:
* `-DLIBCXX_INCLUDE_BENCHMARKS=ON` is only supported for Clang, and not GCC, since the `-stdlib=libc++` option is needed to build Google Benchmark.
Reviewers: danalbert, dberlin, chandlerc, mclow.lists, jroelofs
Subscribers: chandlerc, dberlin, tberghammer, danalbert, srhines, hfinkel
Differential Revision: https://reviews.llvm.org/D22240
llvm-svn: 276049
2016-07-20 07:07:03 +08:00
|
|
|
$ ./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`_.
|