third-party/benchmark/README.md

   1 # Benchmark
   2
   3 [![build-and-test](https://github.com/google/benchmark/workflows/build-and-test/badge.svg)](https://github.com/google/benchmark/actions?query=workflow%3Abuild-and-test)
   4 [![bazel](https://github.com/google/benchmark/actions/workflows/bazel.yml/badge.svg)](https://github.com/google/benchmark/actions/workflows/bazel.yml)
   5 [![pylint](https://github.com/google/benchmark/workflows/pylint/badge.svg)](https://github.com/google/benchmark/actions?query=workflow%3Apylint)
   6 [![test-bindings](https://github.com/google/benchmark/workflows/test-bindings/badge.svg)](https://github.com/google/benchmark/actions?query=workflow%3Atest-bindings)
   7 [![Coverage Status](https://coveralls.io/repos/google/benchmark/badge.svg)](https://coveralls.io/r/google/benchmark)
   8
   9 [![Discord](https://discordapp.com/api/guilds/1125694995928719494/widget.png?style=shield)](https://discord.gg/cz7UX7wKC2)
  10
  11 A library to benchmark code snippets, similar to unit tests. Example:
  12
  13 ```c++
  14 #include <benchmark/benchmark.h>
  15
  16 static void BM_SomeFunction(benchmark::State& state) {
  17   // Perform setup here
  18   for (auto _ : state) {
  19     // This code gets timed
  20     SomeFunction();
  21   }
  22 }
  23 // Register the function as a benchmark
  24 BENCHMARK(BM_SomeFunction);
  25 // Run the benchmark
  26 BENCHMARK_MAIN();
  27 ```
  28
  29 ## Getting Started
  30
  31 To get started, see [Requirements](#requirements) and
  32 [Installation](#installation). See [Usage](#usage) for a full example and the
  33 [User Guide](docs/user_guide.md) for a more comprehensive feature overview.
  34
  35 It may also help to read the [Google Test documentation](https://github.com/google/googletest/blob/main/docs/primer.md)
  36 as some of the structural aspects of the APIs are similar.
  37
  38 ## Resources
  39
  40 [Discussion group](https://groups.google.com/d/forum/benchmark-discuss)
  41
  42 IRC channels:
  43 * [libera](https://libera.chat) #benchmark
  44
  45 [Additional Tooling Documentation](docs/tools.md)
  46
  47 [Assembly Testing Documentation](docs/AssemblyTests.md)
  48
  49 [Building and installing Python bindings](docs/python_bindings.md)
  50
  51 ## Requirements
  52
  53 The library can be used with C++03. However, it requires C++11 to build,
  54 including compiler and standard library support.
  55
  56 The following minimum versions are required to build the library:
  57
  58 * GCC 4.8
  59 * Clang 3.4
  60 * Visual Studio 14 2015
  61 * Intel 2015 Update 1
  62
  63 See [Platform-Specific Build Instructions](docs/platform_specific_build_instructions.md).
  64
  65 ## Installation
  66
  67 This describes the installation process using cmake. As pre-requisites, you'll
  68 need git and cmake installed.
  69
  70 _See [dependencies.md](docs/dependencies.md) for more details regarding supported
  71 versions of build tools._
  72
  73 ```bash
  74 # Check out the library.
  75 $ git clone https://github.com/google/benchmark.git
  76 # Go to the library root directory
  77 $ cd benchmark
  78 # Make a build directory to place the build output.
  79 $ cmake -E make_directory "build"
  80 # Generate build system files with cmake, and download any dependencies.
  81 $ cmake -E chdir "build" cmake -DBENCHMARK_DOWNLOAD_DEPENDENCIES=on -DCMAKE_BUILD_TYPE=Release ../
  82 # or, starting with CMake 3.13, use a simpler form:
  83 # cmake -DCMAKE_BUILD_TYPE=Release -S . -B "build"
  84 # Build the library.
  85 $ cmake --build "build" --config Release
  86 ```
  87 This builds the `benchmark` and `benchmark_main` libraries and tests.
  88 On a unix system, the build directory should now look something like this:
  89
  90 ```
  91 /benchmark
  92   /build
  93     /src
  94       /libbenchmark.a
  95       /libbenchmark_main.a
  96     /test
  97       ...
  98 ```
  99
 100 Next, you can run the tests to check the build.
 101
 102 ```bash
 103 $ cmake -E chdir "build" ctest --build-config Release
 104 ```
 105
 106 If you want to install the library globally, also run:
 107
 108 ```
 109 sudo cmake --build "build" --config Release --target install
 110 ```
 111
 112 Note that Google Benchmark requires Google Test to build and run the tests. This
 113 dependency can be provided two ways:
 114
 115 * Checkout the Google Test sources into `benchmark/googletest`.
 116 * Otherwise, if `-DBENCHMARK_DOWNLOAD_DEPENDENCIES=ON` is specified during
 117   configuration as above, the library will automatically download and build
 118   any required dependencies.
 119
 120 If you do not wish to build and run the tests, add `-DBENCHMARK_ENABLE_GTEST_TESTS=OFF`
 121 to `CMAKE_ARGS`.
 122
 123 ### Debug vs Release
 124
 125 By default, benchmark builds as a debug library. You will see a warning in the
 126 output when this is the case. To build it as a release library instead, add
 127 `-DCMAKE_BUILD_TYPE=Release` when generating the build system files, as shown
 128 above. The use of `--config Release` in build commands is needed to properly
 129 support multi-configuration tools (like Visual Studio for example) and can be
 130 skipped for other build systems (like Makefile).
 131
 132 To enable link-time optimisation, also add `-DBENCHMARK_ENABLE_LTO=true` when
 133 generating the build system files.
 134
 135 If you are using gcc, you might need to set `GCC_AR` and `GCC_RANLIB` cmake
 136 cache variables, if autodetection fails.
 137
 138 If you are using clang, you may need to set `LLVMAR_EXECUTABLE`,
 139 `LLVMNM_EXECUTABLE` and `LLVMRANLIB_EXECUTABLE` cmake cache variables.
 140
 141 To enable sanitizer checks (eg., `asan` and `tsan`), add:
 142 ```
 143  -DCMAKE_C_FLAGS="-g -O2 -fno-omit-frame-pointer -fsanitize=address -fsanitize=thread -fno-sanitize-recover=all"
 144  -DCMAKE_CXX_FLAGS="-g -O2 -fno-omit-frame-pointer -fsanitize=address -fsanitize=thread -fno-sanitize-recover=all "
 145 ```
 146
 147 ### Stable and Experimental Library Versions
 148
 149 The main branch contains the latest stable version of the benchmarking library;
 150 the API of which can be considered largely stable, with source breaking changes
 151 being made only upon the release of a new major version.
 152
 153 Newer, experimental, features are implemented and tested on the
 154 [`v2` branch](https://github.com/google/benchmark/tree/v2). Users who wish
 155 to use, test, and provide feedback on the new features are encouraged to try
 156 this branch. However, this branch provides no stability guarantees and reserves
 157 the right to change and break the API at any time.
 158
 159 ## Usage
 160
 161 ### Basic usage
 162
 163 Define a function that executes the code to measure, register it as a benchmark
 164 function using the `BENCHMARK` macro, and ensure an appropriate `main` function
 165 is available:
 166
 167 ```c++
 168 #include <benchmark/benchmark.h>
 169
 170 static void BM_StringCreation(benchmark::State& state) {
 171   for (auto _ : state)
 172     std::string empty_string;
 173 }
 174 // Register the function as a benchmark
 175 BENCHMARK(BM_StringCreation);
 176
 177 // Define another benchmark
 178 static void BM_StringCopy(benchmark::State& state) {
 179   std::string x = "hello";
 180   for (auto _ : state)
 181     std::string copy(x);
 182 }
 183 BENCHMARK(BM_StringCopy);
 184
 185 BENCHMARK_MAIN();
 186 ```
 187
 188 To run the benchmark, compile and link against the `benchmark` library
 189 (libbenchmark.a/.so). If you followed the build steps above, this library will
 190 be under the build directory you created.
 191
 192 ```bash
 193 # Example on linux after running the build steps above. Assumes the
 194 # `benchmark` and `build` directories are under the current directory.
 195 $ g++ mybenchmark.cc -std=c++11 -isystem benchmark/include \
 196   -Lbenchmark/build/src -lbenchmark -lpthread -o mybenchmark
 197 ```
 198
 199 Alternatively, link against the `benchmark_main` library and remove
 200 `BENCHMARK_MAIN();` above to get the same behavior.
 201
 202 The compiled executable will run all benchmarks by default. Pass the `--help`
 203 flag for option information or see the [User Guide](docs/user_guide.md).
 204
 205 ### Usage with CMake
 206
 207 If using CMake, it is recommended to link against the project-provided
 208 `benchmark::benchmark` and `benchmark::benchmark_main` targets using
 209 `target_link_libraries`.
 210 It is possible to use ```find_package``` to import an installed version of the
 211 library.
 212 ```cmake
 213 find_package(benchmark REQUIRED)
 214 ```
 215 Alternatively, ```add_subdirectory``` will incorporate the library directly in
 216 to one's CMake project.
 217 ```cmake
 218 add_subdirectory(benchmark)
 219 ```
 220 Either way, link to the library as follows.
 221 ```cmake
 222 target_link_libraries(MyTarget benchmark::benchmark)
 223 ```