Debian Codegraph @

third-party/benchmark/README.md

raw
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 ```