diff --git a/README.md b/README.md index 77a2336..f4e6a20 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,9 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/google/benchmark) · [上游 README](https://github.com/google/benchmark/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 + # 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) @@ -8,7 +14,7 @@ [![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: +用于对代码片段进行基准测试（benchmark）的库，类似于单元测试。示例： ```c++ #include @@ -27,47 +33,43 @@ BENCHMARK(BM_SomeFunction); 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. +要开始使用，请参阅[环境要求](#requirements)和 +[安装](#installation)。完整示例见[用法](#usage)，更全面的功能概览见 +[用户指南](docs/user_guide.md)。 -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. +阅读 [Google Test 文档](https://github.com/google/googletest/blob/main/docs/primer.md) +也可能有所帮助，因为 API 在结构上的某些方面较为相似。 -## Resources +## 资源 -[Discussion group](https://groups.google.com/d/forum/benchmark-discuss) +[讨论组](https://groups.google.com/d/forum/benchmark-discuss) -IRC channels: +IRC 频道： * [libera](https://libera.chat) #benchmark -[Additional Tooling Documentation](docs/tools.md) +[附加工具文档](docs/tools.md) -[Assembly Testing Documentation](docs/AssemblyTests.md) +[汇编测试文档](docs/AssemblyTests.md) -[Building and installing Python bindings](docs/python_bindings.md) +[构建并安装 Python 绑定](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. +该库可在 C++11 下使用。不过，构建时需要 C++17，包括编译器和标准库支持。 -_See [dependencies.md](docs/dependencies.md) for more details regarding supported -compilers and standards._ +_有关支持的编译器和标准的更多详情，请参阅 [dependencies.md](docs/dependencies.md)。_ -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). +请参阅[平台特定构建说明](docs/platform_specific_build_instructions.md)。 -## Installation +## 安装 -This describes the installation process using cmake. As pre-requisites, you'll -need git and cmake installed. +本节介绍使用 cmake 的安装流程。作为前提条件，你需要安装 git 和 cmake。 -_See [dependencies.md](docs/dependencies.md) for more details regarding supported -versions of build tools._ +_有关支持的构建工具版本的更多详情，请参阅 [dependencies.md](docs/dependencies.md)。_ ```bash # Check out the library. @@ -81,8 +83,8 @@ $ cmake -DBENCHMARK_DOWNLOAD_DEPENDENCIES=on -DCMAKE_BUILD_TYPE=Release -S . -B # 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` 和 `benchmark_main` 库及测试。 +在 Unix 系统上，构建目录现在应大致如下： ``` /benchmark @@ -94,72 +96,59 @@ On a unix system, the build directory should now look something like this: ... ``` -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: +请注意，Google Benchmark 需要 Google Test 来构建和运行测试。可通过以下两种方式提供该依赖： -* 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. +* 将 Google Test 源码检出到 `benchmark/googletest`。 +* 否则，若在配置时如上指定 `-DBENCHMARK_DOWNLOAD_DEPENDENCIES=ON`， + 库会自动下载并构建任何所需的依赖。 -If you do not wish to build and run the tests, add `-DBENCHMARK_ENABLE_GTEST_TESTS=OFF` -to `CMAKE_ARGS`. +如果你不想构建和运行测试，请将 `-DBENCHMARK_ENABLE_GTEST_TESTS=OFF` +添加到 `CMAKE_ARGS`。 -### Debug vs Release +### Debug 与 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). +默认情况下，benchmark 会作为 debug 库构建。出现这种情况时，输出中会出现警告。若要改为构建 release 库，请在生成构建系统文件时添加 +`-DCMAKE_BUILD_TYPE=Release`，如上所示。在构建命令中使用 `--config Release` 是为了正确支持多配置工具（例如 Visual Studio），对于其他构建系统（如 Makefile）可以省略。 -To enable link-time optimisation, also add `-DBENCHMARK_ENABLE_LTO=true` when -generating the build system files. +要启用链接时优化（link-time optimisation），在生成构建系统文件时还需添加 `-DBENCHMARK_ENABLE_LTO=true`。 -If you are using gcc, you might need to set `GCC_AR` and `GCC_RANLIB` cmake -cache variables, if autodetection fails. +如果你使用 gcc，若自动检测失败，可能需要设置 `GCC_AR` 和 `GCC_RANLIB` cmake +缓存变量。 -If you are using clang, you may need to set `LLVMAR_EXECUTABLE`, -`LLVMNM_EXECUTABLE` and `LLVMRANLIB_EXECUTABLE` cmake cache variables. +如果你使用 clang，可能需要设置 `LLVMAR_EXECUTABLE`、 +`LLVMNM_EXECUTABLE` 和 `LLVMRANLIB_EXECUTABLE` cmake 缓存变量。 -To enable sanitizer checks (eg., `asan` and `tsan`), add: +要启用 sanitizer 检查（例如 `asan` 和 `tsan`），请添加： ``` -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. +main 分支包含基准测试库的最新稳定版本； +其 API 可认为大体稳定，仅在发布新的主版本时才会引入破坏源代码兼容性的变更。 -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. +较新的实验性功能在 +[`v2` 分支](https://github.com/google/benchmark/tree/v2). 上实现和测试。欢迎希望使用、测试新功能并提供反馈的用户尝试该分支。不过，该分支不提供稳定性保证，并保留随时更改和破坏 API 的权利。 -## 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: +定义一个执行待测量代码的函数，使用 `BENCHMARK` 宏将其注册为基准测试函数，并确保提供了合适的 `main` 函数： ```c++ #include @@ -182,9 +171,8 @@ 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. +要运行基准测试，请编译并链接 `benchmark` 库 +（libbenchmark.a/.so）。如果你按照上述构建步骤操作，该库将位于你创建的构建目录下。 ```bash # Example on linux after running the build steps above. Assumes the @@ -193,38 +181,33 @@ $ 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. +或者，链接 `benchmark_main` 库并移除 +上文中的 `BENCHMARK_MAIN();`，以获得相同行为。 -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). +编译后的可执行文件默认会运行所有基准测试。传入 `--help` +标志可查看选项信息，或参阅[用户指南](docs/user_guide.md)。 -### Usage with CMake +### 在 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，建议使用 `target_link_libraries` 链接项目提供的 +`benchmark::benchmark` 或 `benchmark::benchmark_main` 目标。 +当你的目标定义了自己的 `main` 函数时，链接 `benchmark::benchmark`；若要使用默认的基准测试入口点，则链接 `benchmark::benchmark_main`。`benchmark::benchmark_main` 目标会传递链接 +`benchmark::benchmark`。 +可以使用 ```find_package``` 导入已安装的库版本。 ```cmake find_package(benchmark REQUIRED) ``` -Alternatively, ```add_subdirectory``` will incorporate the library directly in -to one's CMake project. +或者，```add_subdirectory``` 会将库直接纳入你的 CMake 项目中。 ```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 目标共享时，应选择对象库（object library）而非静态库： ```cmake add_library(shared_benchmarks OBJECT bench.cc) @@ -233,27 +216,18 @@ 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. +这会链接包含 `BENCHMARK` 注册的对象文件到最终可执行文件中。如果这些注册仅放在中间的 `STATIC` 库中，链接器可能不会复制静态注册符号，因此基准测试不会成为最终可执行文件的一部分。 -#### Embedding Google Benchmark in another CMake project +#### 在另一个 CMake 项目中嵌入 Google Benchmark -There are two common ways to consume Google Benchmark from a CMake project: +从 CMake 项目使用 Google Benchmark 有两种常见方式： -* 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`. +* 使用已安装或由包管理器维护的副本，例如来自系统包管理器或 vcpkg，并通过 `find_package(benchmark REQUIRED)` 导入。 +* 将此仓库添加到源码树中，例如作为子模块或 `FetchContent` 依赖，并调用 `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. +已安装形式将 Google Benchmark 的构建与父项目分离，对于系统包和 vcpkg 通常是最简单的选择。源码树形式在父项目需要固定特定提交或将 Google Benchmark 作为其正常 CMake 配置步骤的一部分进行构建时很有用。 -When embedding from source, most projects should turn off Google Benchmark's -tests and install rules: +从源码嵌入时，大多数项目应关闭 Google Benchmark 的测试和安装规则： ```cmake set(BENCHMARK_ENABLE_GTEST_TESTS OFF CACHE BOOL "" FORCE) @@ -263,28 +237,21 @@ 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 Test，可以在 `benchmark/googletest` 下检出 Google Test 源码，或使用 `BENCHMARK_DOWNLOAD_DEPENDENCIES=ON` 进行配置。对于仅链接 benchmark 库而不构建 Google Benchmark 测试的项目，禁用 `BENCHMARK_ENABLE_GTEST_TESTS` 可避免 Google Test 依赖。 -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. +Google Benchmark 在选择静态或共享库输出时遵循 CMake 的 `BUILD_SHARED_LIBS` 设置。在 Windows 上，请保持此设置与项目的其余部分一致，并确保 benchmark 库和链接它的目标使用相同的运行时库配置。 -### Usage with Bazel +### 与 Bazel 一起使用 -If using Bazel with Bzlmod, add Google Benchmark to your `MODULE.bazel` file: +如果使用带 Bzlmod 的 Bazel，请将 Google Benchmark 添加到 `MODULE.bazel` 文件中： ```starlark bazel_dep(name = "google_benchmark", version = "") ``` -Replace `` with the Google Benchmark release version you want to use. +将 `` 替换为你想使用的 Google Benchmark 发布版本。 -Then link a `cc_binary` or `cc_test` against one of the provided targets: +然后将 `cc_binary` 或 `cc_test` 链接到提供的某个目标之一： ```starlark load("@rules_cc//cc:defs.bzl", "cc_binary") @@ -296,9 +263,6 @@ cc_binary( ) ``` -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. +当你的目标定义自己的 `main` 函数时（包括通过 `BENCHMARK_MAIN()`），使用 `@google_benchmark//:benchmark`。使用 `@google_benchmark//:benchmark_main` 可使用默认的 Google Benchmark 入口点。 -For WORKSPACE setup and more examples, see [Bazel](docs/bazel.md). +有关 WORKSPACE 设置及更多示例，请参阅 [Bazel](docs/bazel.md)。