Skip to content

Commit 92f56ba

Browse files
GuillaumeLagrangeGuillaumeLagrange
committed
docs: add readme for monorepo and google benchmark compat layer
1 parent 2a6438a commit 92f56ba

File tree

2 files changed

+80
-191
lines changed

2 files changed

+80
-191
lines changed

‎README.md‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,13 @@
1-
# codspeed-cpp
1+
<div align="center">
2+
<h1>codspeed-cpp</h1>
3+
4+
[![CI](https://github.com/CodSpeedHQ/codspeed-cpp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/CodSpeedHQ/codspeed-cpp/actions/workflows/ci.yml)
5+
[![Discord](https://img.shields.io/badge/chat%20on-discord-7289da.svg)](https://discord.com/invite/MxpaCfKSqF)
6+
[![CodSpeed Badge](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/CodSpeedHQ/codspeed-cpp)
7+
8+
</div>
9+
10+
This mono-repo contains the integration libraries for using CodSpeed in C++:
11+
12+
- [`codspeed-google-benchmark`](./google_benchmark/): Google Benchmark compatibility layer for CodSpeed
13+
- [`codspeed-core`](./core/): The CodSpeed core library used to integrate with Codspeed runners

‎google_benchmark/README.md‎

Lines changed: 67 additions & 190 deletions
Original file line numberDiff line numberDiff line change
@@ -1,221 +1,98 @@
1-
# Benchmark
1+
<div align="center">
2+
<h1>codspeed-divan-compat</h1>
23

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)
4+
[![CI](https://github.com/CodSpeedHQ/codspeed-cpp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/CodSpeedHQ/codspeed-cpp/actions/workflows/ci.yml)
5+
[![Discord](https://img.shields.io/badge/chat%20on-discord-7289da.svg)](https://discord.com/invite/MxpaCfKSqF)
6+
[![CodSpeed Badge](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/CodSpeedHQ/codspeed-cpp)
87

9-
[![Discord](https://discordapp.com/api/guilds/1125694995928719494/widget.png?style=shield)](https://discord.gg/cz7UX7wKC2)
8+
Google benchmark compatibility layer for CodSpeed
109

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++14 to build,
54-
including compiler and standard library support.
55-
56-
_See [dependencies.md](docs/dependencies.md) for more details regarding supported
57-
compilers and standards._
58-
59-
If you have need for a particular compiler to be supported, patches are very welcome.
60-
61-
See [Platform-Specific Build Instructions](docs/platform_specific_build_instructions.md).
10+
</div>
6211

6312
## Installation
6413

65-
This describes the installation process using cmake. As pre-requisites, you'll
66-
need git and cmake installed.
67-
68-
_See [dependencies.md](docs/dependencies.md) for more details regarding supported
69-
versions of build tools._
70-
71-
```bash
72-
# Check out the library.
73-
$ git clone https://github.com/google/benchmark.git
74-
# Go to the library root directory
75-
$ cd benchmark
76-
# Make a build directory to place the build output.
77-
$ cmake -E make_directory "build"
78-
# Generate build system files with cmake, and download any dependencies.
79-
$ cmake -E chdir "build" cmake -DBENCHMARK_DOWNLOAD_DEPENDENCIES=on -DCMAKE_BUILD_TYPE=Release ../
80-
# or, starting with CMake 3.13, use a simpler form:
81-
# cmake -DBENCHMARK_DOWNLOAD_DEPENDENCIES=on -DCMAKE_BUILD_TYPE=Release -S . -B "build"
82-
# Build the library.
83-
$ cmake --build "build" --config Release
84-
```
85-
This builds the `benchmark` and `benchmark_main` libraries and tests.
86-
On a unix system, the build directory should now look something like this:
14+
The recommended way to use CodSpeed's `google_benchmark` is through `cmake`. Add
15+
the following to your `CMakeLists.txt`:
8716

88-
```
89-
/benchmark
90-
/build
91-
/src
92-
/libbenchmark.a
93-
/libbenchmark_main.a
94-
/test
95-
...
96-
```
17+
```cmake title="CMakeLists.txt"
18+
cmake_minimum_required(VERSION 3.12)
19+
include(FetchContent)
9720
98-
Next, you can run the tests to check the build.
21+
project(my_codspeed_project VERSION 0.0.0 LANGUAGES CXX)
9922
100-
```bash
101-
$ cmake -E chdir "build" ctest --build-config Release
102-
```
23+
set(BENCHMARK_DOWNLOAD_DEPENDENCIES ON)
10324
104-
If you want to install the library globally, also run:
25+
FetchContent_Declare(
26+
google_benchmark
27+
GIT_REPOSITORY https://github.com/CodSpeedHQ/codspeed-cpp
28+
GIT_TAG v1.0.0
29+
SOURCE_SUBDIR
30+
google_benchmark
31+
)
10532
106-
```
107-
sudo cmake --build "build" --config Release --target install
108-
```
33+
FetchContent_MakeAvailable(google_benchmark)
10934
110-
Note that Google Benchmark requires Google Test to build and run the tests. This
111-
dependency can be provided two ways:
35+
# Declare your benchmark executable and its sources here
36+
add_executable(my_benchmark_executable main.cpp)
11237
113-
* Checkout the Google Test sources into `benchmark/googletest`.
114-
* Otherwise, if `-DBENCHMARK_DOWNLOAD_DEPENDENCIES=ON` is specified during
115-
configuration as above, the library will automatically download and build
116-
any required dependencies.
117-
118-
If you do not wish to build and run the tests, add `-DBENCHMARK_ENABLE_GTEST_TESTS=OFF`
119-
to `CMAKE_ARGS`.
120-
121-
### Debug vs Release
122-
123-
By default, benchmark builds as a debug library. You will see a warning in the
124-
output when this is the case. To build it as a release library instead, add
125-
`-DCMAKE_BUILD_TYPE=Release` when generating the build system files, as shown
126-
above. The use of `--config Release` in build commands is needed to properly
127-
support multi-configuration tools (like Visual Studio for example) and can be
128-
skipped for other build systems (like Makefile).
129-
130-
To enable link-time optimisation, also add `-DBENCHMARK_ENABLE_LTO=true` when
131-
generating the build system files.
132-
133-
If you are using gcc, you might need to set `GCC_AR` and `GCC_RANLIB` cmake
134-
cache variables, if autodetection fails.
135-
136-
If you are using clang, you may need to set `LLVMAR_EXECUTABLE`,
137-
`LLVMNM_EXECUTABLE` and `LLVMRANLIB_EXECUTABLE` cmake cache variables.
138-
139-
To enable sanitizer checks (eg., `asan` and `tsan`), add:
38+
# Link your executable against the `benchmark::benchmark` library
39+
target_link_libraries(my_benchmark_example benchmark::benchmark)
14040
```
141-
-DCMAKE_C_FLAGS="-g -O2 -fno-omit-frame-pointer -fsanitize=address -fsanitize=thread -fno-sanitize-recover=all"
142-
-DCMAKE_CXX_FLAGS="-g -O2 -fno-omit-frame-pointer -fsanitize=address -fsanitize=thread -fno-sanitize-recover=all "
143-
```
144-
145-
### Stable and Experimental Library Versions
146-
147-
The main branch contains the latest stable version of the benchmarking library;
148-
the API of which can be considered largely stable, with source breaking changes
149-
being made only upon the release of a new major version.
150-
151-
Newer, experimental, features are implemented and tested on the
152-
[`v2` branch](https://github.com/google/benchmark/tree/v2). Users who wish
153-
to use, test, and provide feedback on the new features are encouraged to try
154-
this branch. However, this branch provides no stability guarantees and reserves
155-
the right to change and break the API at any time.
15641

15742
## Usage
15843

159-
### Basic usage
160-
161-
Define a function that executes the code to measure, register it as a benchmark
162-
function using the `BENCHMARK` macro, and ensure an appropriate `main` function
163-
is available:
44+
### Creating benchmark
16445

165-
```c++
166-
#include <benchmark/benchmark.h>
46+
Here is an example benchmark, follow the [google benchmark documentation](https://github.com/google/benchmark/blob/main/docs/user_guide.md) for more advanced usage.
16747

168-
static void BM_StringCreation(benchmark::State& state) {
169-
for (auto _ : state)
170-
std::string empty_string;
171-
}
172-
// Register the function as a benchmark
173-
BENCHMARK(BM_StringCreation);
174-
175-
// Define another benchmark
176-
static void BM_StringCopy(benchmark::State& state) {
48+
```cpp title="main.cpp"
49+
static void BM_StringCopy(benchmark::State &state) {
17750
std::string x = "hello";
178-
for (auto _ : state)
51+
for (auto _ : state) {
17952
std::string copy(x);
53+
}
18054
}
18155
BENCHMARK(BM_StringCopy);
18256

183-
BENCHMARK_MAIN();
184-
```
185-
186-
To run the benchmark, compile and link against the `benchmark` library
187-
(libbenchmark.a/.so). If you followed the build steps above, this library will
188-
be under the build directory you created.
57+
static void BM_memcpy(benchmark::State &state) {
58+
char *src = new char[state.range(0)];
59+
char *dst = new char[state.range(0)];
60+
memset(src, 'x', state.range(0));
61+
for (auto _ : state)
62+
memcpy(dst, src, state.range(0));
63+
delete[] src;
64+
delete[] dst;
65+
}
18966

190-
```bash
191-
# Example on linux after running the build steps above. Assumes the
192-
# `benchmark` and `build` directories are under the current directory.
193-
$ g++ mybenchmark.cc -std=c++11 -isystem benchmark/include \
194-
-Lbenchmark/build/src -lbenchmark -lpthread -o mybenchmark
67+
BENCHMARK(BM_memcpy)->Range(8, 8 << 10);
19568
```
19669
197-
Alternatively, link against the `benchmark_main` library and remove
198-
`BENCHMARK_MAIN();` above to get the same behavior.
70+
### Compiling and running benchmarks
19971
200-
The compiled executable will run all benchmarks by default. Pass the `--help`
201-
flag for option information or see the [User Guide](docs/user_guide.md).
72+
To build and run the benchmark executable
20273
203-
### Usage with CMake
204-
205-
If using CMake, it is recommended to link against the project-provided
206-
`benchmark::benchmark` and `benchmark::benchmark_main` targets using
207-
`target_link_libraries`.
208-
It is possible to use ```find_package``` to import an installed version of the
209-
library.
210-
```cmake
211-
find_package(benchmark REQUIRED)
212-
```
213-
Alternatively, ```add_subdirectory``` will incorporate the library directly in
214-
to one's CMake project.
215-
```cmake
216-
add_subdirectory(benchmark)
21774
```
218-
Either way, link to the library as follows.
219-
```cmake
220-
target_link_libraries(MyTarget benchmark::benchmark)
75+
$ mkdir build
76+
$ cd build
77+
$ cmake -DCODSPEED_MODE=instrumentation ..
78+
...
79+
-- Configuring done (8.9s)
80+
-- Generating done (0.1s)
81+
-- Build files have been written to: /home/user/my-project/build
82+
$ make -j
83+
...
84+
[ 98%] Built target reporter_output_test
85+
[100%] Linking CXX executable benchmark_gtest
86+
[100%] Built target benchmark_gtest
87+
$ ./my-bench
88+
NOTICE: codspeed is enabled, but no performance measurement will be made since it's running in an unknown environment.
89+
Checked: main.cpp::BM_rand_vector
90+
Checked: main.cpp::BM_StringCopy
91+
Checked: main.cpp::BM_memcpy[8]
92+
Checked: main.cpp::BM_memcpy[64]
93+
Checked: main.cpp::BM_memcpy[512]
94+
Checked: main.cpp::BM_memcpy[4096]
95+
Checked: main.cpp::BM_memcpy[8192]
22196
```
97+
98+
For more informations, please checkout the [codspeed documentation](https://docs.codspeed.io/benchmarks/cpp)

0 commit comments

Comments
 (0)