From ca61102e3fc3304a7be0d097a9dabc1b61d6a7b2 Mon Sep 17 00:00:00 2001 From: wehub-resource-sync Date: Mon, 13 Jul 2026 10:17:49 +0000 Subject: [PATCH] docs: preserve upstream English README --- README.en.md | 304 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 304 insertions(+) create mode 100644 README.en.md diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..77a2336 --- /dev/null +++ b/README.en.md @@ -0,0 +1,304 @@ +# Benchmark + +[![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) +[![bazel](https://github.com/google/benchmark/actions/workflows/bazel.yml/badge.svg)](https://github.com/google/benchmark/actions/workflows/bazel.yml) +[![test-bindings](https://github.com/google/benchmark/workflows/test-bindings/badge.svg)](https://github.com/google/benchmark/actions?query=workflow%3Atest-bindings) +[![Coverage Status](https://coveralls.io/repos/google/benchmark/badge.svg)](https://coveralls.io/r/google/benchmark) +[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/google/benchmark/badge)](https://securityscorecards.dev/viewer/?uri=github.com/google/benchmark) + +[![Discord](https://discordapp.com/api/guilds/1125694995928719494/widget.png?style=shield)](https://discord.gg/cz7UX7wKC2) + +A library to benchmark code snippets, similar to unit tests. Example: + +```c++ +#include +#include + +static void BM_SomeFunction(benchmark::State& state) { + // Perform setup here + for (auto _ : state) { + // This code gets timed + SomeFunction(); + } +} +// Register the function as a benchmark +BENCHMARK(BM_SomeFunction); +// Run the benchmark +BENCHMARK_MAIN(); +``` + +## Getting Started + +To get started, see [Requirements](#requirements) and +[Installation](#installation). See [Usage](#usage) for a full example and the +[User Guide](docs/user_guide.md) for a more comprehensive feature overview. + +It may also help to read the [Google Test documentation](https://github.com/google/googletest/blob/main/docs/primer.md) +as some of the structural aspects of the APIs are similar. + +## Resources + +[Discussion group](https://groups.google.com/d/forum/benchmark-discuss) + +IRC channels: +* [libera](https://libera.chat) #benchmark + +[Additional Tooling Documentation](docs/tools.md) + +[Assembly Testing Documentation](docs/AssemblyTests.md) + +[Building and installing Python bindings](docs/python_bindings.md) + +## Requirements + +The library can be used with C++11. However, it requires C++17 to build, +including compiler and standard library support. + +_See [dependencies.md](docs/dependencies.md) for more details regarding supported +compilers and standards._ + +If you have need for a particular compiler to be supported, patches are very welcome. + +See [Platform-Specific Build Instructions](docs/platform_specific_build_instructions.md). + +## Installation + +This describes the installation process using cmake. As pre-requisites, you'll +need git and cmake installed. + +_See [dependencies.md](docs/dependencies.md) for more details regarding supported +versions of build tools._ + +```bash +# Check out the library. +$ git clone https://github.com/google/benchmark.git +# Go to the library root directory +$ cd benchmark +# Make a build directory to place the build output. +$ cmake -E make_directory "build" +# Generate build system files with cmake, and download any dependencies. +$ cmake -DBENCHMARK_DOWNLOAD_DEPENDENCIES=on -DCMAKE_BUILD_TYPE=Release -S . -B "build" +# Build the library. +$ cmake --build "build" --config Release +``` +This builds the `benchmark` and `benchmark_main` libraries and tests. +On a unix system, the build directory should now look something like this: + +``` +/benchmark + /build + /src + /libbenchmark.a + /libbenchmark_main.a + /test + ... +``` + +Next, you can run the tests to check the build. + +```bash +$ cmake -E chdir "build" ctest --build-config Release +``` + +If you want to install the library globally, also run: + +``` +sudo cmake --build "build" --config Release --target install +``` + +Note that Google Benchmark requires Google Test to build and run the tests. This +dependency can be provided two ways: + +* Checkout the Google Test sources into `benchmark/googletest`. +* Otherwise, if `-DBENCHMARK_DOWNLOAD_DEPENDENCIES=ON` is specified during + configuration as above, the library will automatically download and build + any required dependencies. + +If you do not wish to build and run the tests, add `-DBENCHMARK_ENABLE_GTEST_TESTS=OFF` +to `CMAKE_ARGS`. + +### Debug vs Release + +By default, benchmark builds as a debug library. You will see a warning in the +output when this is the case. To build it as a release library instead, add +`-DCMAKE_BUILD_TYPE=Release` when generating the build system files, as shown +above. The use of `--config Release` in build commands is needed to properly +support multi-configuration tools (like Visual Studio for example) and can be +skipped for other build systems (like Makefile). + +To enable link-time optimisation, also add `-DBENCHMARK_ENABLE_LTO=true` when +generating the build system files. + +If you are using gcc, you might need to set `GCC_AR` and `GCC_RANLIB` cmake +cache variables, if autodetection fails. + +If you are using clang, you may need to set `LLVMAR_EXECUTABLE`, +`LLVMNM_EXECUTABLE` and `LLVMRANLIB_EXECUTABLE` cmake cache variables. + +To enable sanitizer checks (eg., `asan` and `tsan`), add: +``` + -DCMAKE_C_FLAGS="-g -O2 -fno-omit-frame-pointer -fsanitize=address -fsanitize=thread -fno-sanitize-recover=all" + -DCMAKE_CXX_FLAGS="-g -O2 -fno-omit-frame-pointer -fsanitize=address -fsanitize=thread -fno-sanitize-recover=all " +``` + +### Stable and Experimental Library Versions + +The main branch contains the latest stable version of the benchmarking library; +the API of which can be considered largely stable, with source breaking changes +being made only upon the release of a new major version. + +Newer, experimental, features are implemented and tested on the +[`v2` branch](https://github.com/google/benchmark/tree/v2). Users who wish +to use, test, and provide feedback on the new features are encouraged to try +this branch. However, this branch provides no stability guarantees and reserves +the right to change and break the API at any time. + +## Usage + +### Basic usage + +Define a function that executes the code to measure, register it as a benchmark +function using the `BENCHMARK` macro, and ensure an appropriate `main` function +is available: + +```c++ +#include + +static void BM_StringCreation(benchmark::State& state) { + for (auto _ : state) + std::string empty_string; +} +// Register the function as a benchmark +BENCHMARK(BM_StringCreation); + +// Define another benchmark +static void BM_StringCopy(benchmark::State& state) { + std::string x = "hello"; + for (auto _ : state) + std::string copy(x); +} +BENCHMARK(BM_StringCopy); + +BENCHMARK_MAIN(); +``` + +To run the benchmark, compile and link against the `benchmark` library +(libbenchmark.a/.so). If you followed the build steps above, this library will +be under the build directory you created. + +```bash +# Example on linux after running the build steps above. Assumes the +# `benchmark` and `build` directories are under the current directory. +$ g++ mybenchmark.cc -std=c++11 -isystem benchmark/include \ + -Lbenchmark/build/src -lbenchmark -lpthread -o mybenchmark +``` + +Alternatively, link against the `benchmark_main` library and remove +`BENCHMARK_MAIN();` above to get the same behavior. + +The compiled executable will run all benchmarks by default. Pass the `--help` +flag for option information or see the [User Guide](docs/user_guide.md). + +### Usage with CMake + +If using CMake, it is recommended to link against the project-provided +`benchmark::benchmark` or `benchmark::benchmark_main` targets using +`target_link_libraries`. Link to `benchmark::benchmark` when your target +defines its own `main` function, or link to `benchmark::benchmark_main` to use +the default benchmark entry point. The `benchmark::benchmark_main` target links +`benchmark::benchmark` transitively. +It is possible to use ```find_package``` to import an installed version of the +library. +```cmake +find_package(benchmark REQUIRED) +``` +Alternatively, ```add_subdirectory``` will incorporate the library directly in +to one's CMake project. +```cmake +add_subdirectory(benchmark) +``` +Either way, link to the library as follows. +```cmake +target_link_libraries(MyTarget benchmark::benchmark) +# Or, when you do not define your own main: +target_link_libraries(MyTarget benchmark::benchmark_main) +``` +When benchmark sources are shared through an intermediate CMake target, choose +an object library instead of a static library: + +```cmake +add_library(shared_benchmarks OBJECT bench.cc) +target_link_libraries(shared_benchmarks benchmark::benchmark_main) +add_executable(runnable_benchmarks) +target_link_libraries(runnable_benchmarks shared_benchmarks) +``` + +This links the object file that contains `BENCHMARK` registrations into the +final executable. If those registrations are placed only in an intermediate +`STATIC` library, the linker may not copy static registration symbols, and thus +benchmarks will not be part of the final executable. + +#### Embedding Google Benchmark in another CMake project + +There are two common ways to consume Google Benchmark from a CMake project: + +* Use an installed or package-managed copy, for example from a system package + manager or vcpkg, and import it with `find_package(benchmark REQUIRED)`. +* Add this repository to the source tree, for example as a submodule or + `FetchContent` dependency, and call `add_subdirectory`. + +The installed form keeps Google Benchmark's build separate from the parent +project and is usually the simplest choice for system packages and vcpkg. The +source-tree form is useful when the parent project wants to pin a specific +commit or build Google Benchmark as part of its normal CMake configure step. + +When embedding from source, most projects should turn off Google Benchmark's +tests and install rules: + +```cmake +set(BENCHMARK_ENABLE_GTEST_TESTS OFF CACHE BOOL "" FORCE) +set(BENCHMARK_ENABLE_TESTING OFF CACHE BOOL "" FORCE) +set(BENCHMARK_ENABLE_INSTALL OFF CACHE BOOL "" FORCE) +add_subdirectory(third_party/benchmark) +target_link_libraries(MyTarget benchmark::benchmark) +``` + +If Google Test is not already provided by the parent build, either check out the +Google Test sources under `benchmark/googletest` or configure with +`BENCHMARK_DOWNLOAD_DEPENDENCIES=ON`. For projects that only link the benchmark +library and do not build Google Benchmark's tests, disabling +`BENCHMARK_ENABLE_GTEST_TESTS` avoids the Google Test dependency. + +Google Benchmark follows CMake's `BUILD_SHARED_LIBS` setting when selecting +static or shared library output. On Windows, keep this setting consistent with +the rest of the project and make sure the same runtime library configuration is +used across the benchmark library and the targets that link it. + +### Usage with Bazel + +If using Bazel with Bzlmod, add Google Benchmark to your `MODULE.bazel` file: + +```starlark +bazel_dep(name = "google_benchmark", version = "") +``` + +Replace `` with the Google Benchmark release version you want to use. + +Then link a `cc_binary` or `cc_test` against one of the provided targets: + +```starlark +load("@rules_cc//cc:defs.bzl", "cc_binary") + +cc_binary( + name = "my_benchmark", + srcs = ["my_benchmark.cc"], + deps = ["@google_benchmark//:benchmark_main"], +) +``` + +Use `@google_benchmark//:benchmark` when your target defines its own `main` +function, including through `BENCHMARK_MAIN()`. Use +`@google_benchmark//:benchmark_main` to use the default Google Benchmark entry +point. + +For WORKSPACE setup and more examples, see [Bazel](docs/bazel.md).