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