Documentation: Adding instructions to build the "basic usage" example

[kanak]

Hi benchmark authors,

I saw the library used to great effect in a course on C++ Optimization [1] and was eager to try the examples at home. I'm using Fedora 28 Linux with G++ 8.1.1, cmake 3.11.2 and GNU make 4.2.1 .

The instructions for building and installing the library were clear and easy to follow. I was able to get a build the library itself quite easily. Thank you for this!

I then wanted to build and run the "Basic Usage" example. I immediately ran into a roadblock because the linker kept complaining about things like undefined reference to benchmark::State::StartKeepRunning(). I got some help from the friendly folks at the #googlebenchmark chatroom, but we weren't able to resolve the issue.

I ended up spending a few hours googling 'google benchmark tutorial' to find someone who had successfully compiled a benchmark program. After a few false starts, I found an article from 2014 [2] that helped me resolve the issue.

The issue was that I was running

g++ -std=c++11  -lbenchmark -lpthread  benchmark.cpp   -o benchmark

instead of

g++ benchmark.cpp -std=c++11 -lbenchmark -lpthread -O2 -o benchmark

(Note the position of benchmark.cpp relative to -lbenchmark). The reason this happened is that I had set LDFLAGS=-lbenchmark instead of using LDLIBS=-lbenchmark in my Makefile.

I would like to update the documentation so that it has additional information on how to build the basic usage example. The current instruction to also add -lpthread on g++ is helpful, but I think we could flesh it out further.

I was curious if you thought this was a good idea and if so, where I should add this info and what form it should take. I think that spelling out the g++ command or even better, providing an example Makefile would go a long way.

Thanks!

[1] https://www.safaribooksonline.com/library/view/high-performance-computing-and/9781491967560/
[2] http://www.cookandcommit.eu/2014/09/tiny-c-benchmark-framework_29.html

[dmah42]

I'm a fan of any extra documentation. The README is getting a bit long though, so I wonder if a 'troubleshooting' or 'faq' doc might be useful with some of the tips pulled out from the README.

[kanak]

I'm happy to contribute either of those. Another option is to start a new document in docs/ called "Getting Started" or "Compiling your first benchmark".

[dmah42]

That would be great. README.md should likely be minimised with links to other docs :)