gauge is a flexible C++ benchmarking tool.
We have tested gauge on various versions of Windows, Linux and Mac. You can see the status by selecting the gauge project on the Steinwurf buildbot page:
We use the waf
build-system to build the gauge static library.
With some additional tools which may be found at waf
To build gauge run the following command:
./waf configure --bundle-path=~/dev/bundle_dependencies ./waf build
Substitute the ~/dev/bundle_dependencies
with the path where you wish
waf to download gauge's dependencies. You may omit this option then waf
will download the dependencies into the gauge project folder.
You should now have the libgauge.a
static lib. It also build the boost
dependencies as static libs. In the gauge directory type find . -name "*.a"
to see the libraries produced. We need to use the path to the libraries when
using gauge with our own applications as shown in the following.
When building the static lib, waf will also build the gauge_example
executable.
Depending on your platform you should be able to launch it by running:
./build/linux/examples/sample_benchmarks/gauge_example
See various use-cases in the examples
folder. The following will be used to
explain the basic concepts of gauge. To try it out save the following code in a
file called main.cpp
#include <gauge/gauge.hpp> #include <gauge/console_printer.hpp> #include <vector> BENCHMARK(MyTest, RunThis, 100) { std::vector<int> integers; for(int i = 0; i < 2048; ++i) { integers.push_back(i); } // This is where the clock runs RUN{ for(uint i = 1; i < integers.size(); ++i) { integers[i] += integers[i-1]; } } } int main(int argc, const char* argv[]) { gauge::runner::instance().printers().push_back( std::make_shared<gauge::console_printer>()); gauge::runner::run_benchmarks(argc, argv); return 0; }
In the above we use the BENCHMARK
macro which takes 3 parameters:
- The name of the test-case in this case
MyTest
- The name of the benchmark in this case
RunThis
- The number of runs to complete in this case 100.
The measurement will not start until we hit the RUN
macro. Depending
on the type of benchmark (the default is time) the code inside RUN
will
be executed several times (we refer to this as the number of iterations).
When gauge is satisfied with the measurement we exit the run loop. For every
BENCHMARK
we may only call RUN
once.
Using g++
the example code may be compiled as:
g++ main.cpp -o benchmark --std=c++0x -I../path_to_gauge/ -L../path_to_libguage -lgauge -L../path_to_libboostxyz -lboost_chrono -lboost_program_options -lboost_system -lrt
We assume you are using the boost libs built together with gauge. In the future we will attempt also support boost libraries installed using your package manager or similar.
You should now be able to run the benchmark using:
./benchmark
gauge is available under the BSD license, see the LICENSE.rst file.
We have create gauge to fit our specific purpose, however we hope that others may also find it useful. When designing gauge we found inspiration in these other nice projects:
- Qt's benchmark tools part of QTestLib.
- Nick Bruun's Hayai C++ benchmark tool, who also provided the nice terminal colors.
- The Google Test framework.
Thanks for all the fish.