Add documentation on Running Your First Benchmark #622
Conversation
|
I'm new to the library and also not a native speaker, so I'm open to all feedback. I'm also happy to add Ubuntu Linux instructions or additional instructions using Clang if necessary. I also did not remove or otherwise refactor any docs in the Readme, I can help with that work as well. |
docs/RunningFirstBenchmark.md
Outdated
| ``` | ||
|
|
||
| Notes: | ||
| * We use `-std=c++11` because benchmark library requires at least c++11. Replacing it with `c++14` or `c++17` also work. |
There was a problem hiding this comment.
This isn't true, i think right now, c++11 is still not required for consumers
| `make install` should result in lines that look like: | ||
|
|
||
| ``` | ||
| -- Install configuration: "RELEASE" |
There was a problem hiding this comment.
This is quite messy.
I'm thinking that maybe you either want to specify a custom install prefix, or not install at all.
In either case, you'll need to specify the include/link paths.
Or maybe just use the packaged version?
There was a problem hiding this comment.
Sadly, google benchmark is not available in the Fedora 28 repository right now, so I have to compile it from source.
I'll prepare instructions for the no install use case. The "install" related bits can then be an "appendix" in this document or just removed.
In #619 , the need for documentation aimed at rank beginners was mentioned. Specifically, the need for exact command line incantations and expected outputs. This commit adds a new file inside docs that contains this beginner-friendly documentation. The documentation was verified against Fedora 28, but can be extended to add ubuntu and other os information.
|
✅ Build benchmark 1297 completed (commit 6c0ae4037f by @) |
|
|
||
| This tutorial is aimed at people new to the library and shows you how to run benchmarks with the Google Benchmark library. | ||
|
|
||
| # Install the prerequisites |
There was a problem hiding this comment.
This should only be necessary if a package is not available. Ie, it might be worth having a section on getting the library first, with installation from source being one of the options.
| * cmake : to build google benchmark | ||
| * make : to build google benchmark. Advanced users can use an alternative cmake backend like ninja. | ||
| * g++ : to compile your c++ code. Advanced users can use other compilers like clang instead. | ||
|
|
There was a problem hiding this comment.
cmake or bazel (bazel is preferred)
make or ninja or visual studio for windows
g++ or clang++ can be replaced by "A C++ compiler with C++11 support"
| * g++ : 8.1.1 20180502 | ||
| * cmake : 3.11.2 | ||
| * gnu make: 4.2.1 | ||
| * git: 2.17.1 |
There was a problem hiding this comment.
I think it's better to avoid this specificity and just have the users install the packages however they know how. there are too many platforms and variants to go into detail.
|
|
||
| # Build and install Google Benchmark | ||
|
|
||
| Follow the instructions elsewhere to build and install the google-benchmark library. |
There was a problem hiding this comment.
Add a doc on building and (optionally) installing and link to it, then remove the same instructions from the base README file.
| -- Installing: /usr/local/lib/cmake/benchmark/benchmarkTargets-release.cmake | ||
| ``` | ||
|
|
||
| Note the locations of the header file (`benchmark.h`) and the static library (`libbenchmark.a`); you might have to tell your compiler to look for libraries in those paths. Things worked out of the box in Fedora 28. |
There was a problem hiding this comment.
this should not be necessary unless the user overrides the install location, in which case they know what they're doing. :)
|
|
||
| # Build your first benchmark | ||
|
|
||
| Save this file as `BenchmarkMain.cpp`: |
There was a problem hiding this comment.
maybe leave out the specifics of naming if you can. there are many standards around and this is irrelevant for library usage.
|
|
||
| ``` | ||
| g++ BenchMain.cpp -std=c++11 -lbenchmark -lpthread -O2 -o BenchMain | ||
| ``` |
There was a problem hiding this comment.
again, we work against many platforms. I think it's better to have more generic instructions about building your executable and linking against the library, then have a section below on requirements like pthread and benchmark. Users on different platforms will have different ways of linking against those libraries.
|
is this still something you wanted to pursue? |
|
@dominichamon : I would like to abandon this effort. I understand the concerns laid out here, that this documentation would be too specific and overly prescriptive and unsuitable in its form as a piece of official documentation. However, I wrote this when I was running into some really basic problems (in retrospect), such as passing the Thank you for your time and for the wonderful library. |
|
thanks, @kanak |
In #619 , the need for
documentation aimed at rank beginners was mentioned. Specifically, the
need for exact command line incantations and expected outputs.
This commit adds a new file inside docs that contains this
beginner-friendly documentation. The documentation was verified
against Fedora 28, but can be extended to add ubuntu and other os
information.