README.md
1# Benchmark
2
3[](https://github.com/google/benchmark/actions?query=workflow%3Abuild-and-test)
4[](https://github.com/google/benchmark/actions/workflows/bazel.yml)
5[](https://github.com/google/benchmark/actions?query=workflow%3Apylint)
6[](https://github.com/google/benchmark/actions?query=workflow%3Atest-bindings)
7
8[](https://travis-ci.org/google/benchmark)
9[](https://coveralls.io/r/google/benchmark)
10
11
12A library to benchmark code snippets, similar to unit tests. Example:
13
14```c++
15#include <benchmark/benchmark.h>
16
17static 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
25BENCHMARK(BM_SomeFunction);
26// Run the benchmark
27BENCHMARK_MAIN();
28```
29
30## Getting Started
31
32To 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
36It may also help to read the [Google Test documentation](https://github.com/google/googletest/blob/master/docs/primer.md)
37as 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
43IRC 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
52The library can be used with C++03. However, it requires C++11 to build,
53including compiler and standard library support.
54
55The 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
62See [Platform-Specific Build Instructions](docs/platform_specific_build_instructions.md).
63
64## Installation
65
66This describes the installation process using cmake. As pre-requisites, you'll
67need git and cmake installed.
68
69_See [dependencies.md](docs/dependencies.md) for more details regarding supported
70versions 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```
86This builds the `benchmark` and `benchmark_main` libraries and tests.
87On 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
99Next, you can run the tests to check the build.
100
101```bash
102$ cmake -E chdir "build" ctest --build-config Release
103```
104
105If you want to install the library globally, also run:
106
107```
108sudo cmake --build "build" --config Release --target install
109```
110
111Note that Google Benchmark requires Google Test to build and run the tests. This
112dependency 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
119If you do not wish to build and run the tests, add `-DBENCHMARK_ENABLE_GTEST_TESTS=OFF`
120to `CMAKE_ARGS`.
121
122### Debug vs Release
123
124By default, benchmark builds as a debug library. You will see a warning in the
125output 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
127above. The use of `--config Release` in build commands is needed to properly
128support multi-configuration tools (like Visual Studio for example) and can be
129skipped for other build systems (like Makefile).
130
131To enable link-time optimisation, also add `-DBENCHMARK_ENABLE_LTO=true` when
132generating the build system files.
133
134If you are using gcc, you might need to set `GCC_AR` and `GCC_RANLIB` cmake
135cache variables, if autodetection fails.
136
137If 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
142The main branch contains the latest stable version of the benchmarking library;
143the API of which can be considered largely stable, with source breaking changes
144being made only upon the release of a new major version.
145
146Newer, experimental, features are implemented and tested on the
147[`v2` branch](https://github.com/google/benchmark/tree/v2). Users who wish
148to use, test, and provide feedback on the new features are encouraged to try
149this branch. However, this branch provides no stability guarantees and reserves
150the right to change and break the API at any time.
151
152## Usage
153
154### Basic usage
155
156Define a function that executes the code to measure, register it as a benchmark
157function using the `BENCHMARK` macro, and ensure an appropriate `main` function
158is available:
159
160```c++
161#include <benchmark/benchmark.h>
162
163static void BM_StringCreation(benchmark::State& state) {
164 for (auto _ : state)
165 std::string empty_string;
166}
167// Register the function as a benchmark
168BENCHMARK(BM_StringCreation);
169
170// Define another benchmark
171static void BM_StringCopy(benchmark::State& state) {
172 std::string x = "hello";
173 for (auto _ : state)
174 std::string copy(x);
175}
176BENCHMARK(BM_StringCopy);
177
178BENCHMARK_MAIN();
179```
180
181To run the benchmark, compile and link against the `benchmark` library
182(libbenchmark.a/.so). If you followed the build steps above, this library will
183be 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
192Alternatively, link against the `benchmark_main` library and remove
193`BENCHMARK_MAIN();` above to get the same behavior.
194
195The compiled executable will run all benchmarks by default. Pass the `--help`
196flag for option information or see the [User Guide](docs/user_guide.md).
197
198### Usage with CMake
199
200If using CMake, it is recommended to link against the project-provided
201`benchmark::benchmark` and `benchmark::benchmark_main` targets using
202`target_link_libraries`.
203It is possible to use ```find_package``` to import an installed version of the
204library.
205```cmake
206find_package(benchmark REQUIRED)
207```
208Alternatively, ```add_subdirectory``` will incorporate the library directly in
209to one's CMake project.
210```cmake
211add_subdirectory(benchmark)
212```
213Either way, link to the library as follows.
214```cmake
215target_link_libraries(MyTarget benchmark::benchmark)
216```
217
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}