What's the difference between gtest.lib and gtest_main.lib?

Question

Google's C++ Test Framework has two output libraries: one is gtest.lib and the other one is gtest_main.lib. According to Nik Reiman's answer on how to setup gtest with Visual Studio, we should link to gtest_main.lib but I'm linking to gtest.lib and the sample test cases that I have are running fine.

What's the difference between the two libraries and does it matter which one I link to?

Answer 1

the only reasonable difference is that gtest_main.lib provides a default implementation of a test application entry point (i.e. main function):

Citation from Getting started with Google C++ Testing Framework:

"[...] maybe you think that writing all those main() functions is too much work? We agree with you completely and that's why Google Test provides a basic implementation of main(). If it fits your needs, then just link your test with gtest_main library and you are good to go."

If you want to write your main function yourself - you should link with gtest.lib.

Answer 2

In fact, the various build methods available for googletest don't build the libraries consistently. At least this part is consistent though:

gtest

The gtest library (variously called gtest.a, gtest.so, gtest.lib or libgtest.a, etc, depending on your platform and whether you are using the shared library) contains the object code for the gtest framework, including everything that tests need. Basically it implements everything you can use from gtest/gest.h. It does not include a main() method.

gtest_main

It includes a trivial main method that will launch the registered tests, something like this (as of 1.8):

GTEST_API_ int main(int argc, char **argv) {
  printf("Running main() from gtest_main.cc\n");
  testing::InitGoogleTest(&argc, argv);
  return RUN_ALL_TESTS();
}

Now the inconsistent part is that gtest_main sometimes also includes everything from gtest, so that you only need to link against either gtest (if you want to write your own main() method) or gtest_main (if you want the use the canned main method above). This is the case, for example, if you use the Makefile build included in googletest/make:

gtest.a : gtest-all.o
    $(AR) $(ARFLAGS) $@ $^

gtest_main.a : gtest-all.o gtest_main.o
    $(AR) $(ARFLAGS) $@ $^

Clearly, gtest_main.a includes everything that gtest.a does, plus the gtest-main.o object which includes the main function.

With the CMake build, however, the situation is different, at least for some build artifacts. For example, for the main libraries we have:

cxx_library(gtest "${cxx_strict}" src/gtest-all.cc)
cxx_library(gtest_main "${cxx_strict}" src/gtest_main.cc)
target_link_libraries(gtest_main gtest)

Here, gtest_main only contains the main function and nothing much else¹. The target_link_libraries line tells anything else using this CMake build that if you link gtest_main you should also link gtest, so in the rest of the file it is common to see things linked only against gtest_main. Indeed, the documentation earlier in the CMakeLists.txt file makes this explicit:

# Defines the gtest & gtest_main libraries.  User tests should link
# with one of them.

Note the "with one one them" part. What they really mean is that if you are building with this same CMake system you can do that, but at the actual link level you need both libtest.a and libgtest_main.a or else you won't pull in what you need to write a test.

---

¹ Indeed, with CMake libgtest.a ends up at 1,755,216 bytes, and libgtest_main.a is only a paltry 3,836 bytes. With the ../make/Makefile build, those figures are 3,365,240 and 3,398,356 respectively. Evidently there are differences beyond the files included that blow up the size of the Makefile version.

Answer 3

You will need to link gtest.lib to your project with the unit tests.