Home | History | Annotate | Download | only in docs 
      1 ## Using GoogleTest from various build systems ##
      2 
      3 GoogleTest comes with pkg-config files that can be used to determine all
      4 necessary flags for compiling and linking to GoogleTest (and GoogleMock).
      5 Pkg-config is a standardised plain-text format containing
      6 
      7   * the includedir (-I) path
      8   * necessary macro (-D) definitions
      9   * further required flags (-pthread)
     10   * the library (-L) path
     11   * the library (-l) to link to
     12 
     13 All current build systems support pkg-config in one way or another. For
     14 all examples here we assume you want to compile the sample
     15 `samples/sample3_unittest.cc`.
     16 
     17 
     18 ### CMake ###
     19 
     20 Using `pkg-config` in CMake is fairly easy:
     21 
     22 ``` cmake
     23 cmake_minimum_required(VERSION 3.0)
     24 
     25 cmake_policy(SET CMP0048 NEW)
     26 project(my_gtest_pkgconfig VERSION 0.0.1 LANGUAGES CXX)
     27 
     28 find_package(PkgConfig)
     29 pkg_search_module(GTEST REQUIRED gtest_main)
     30 
     31 add_executable(testapp samples/sample3_unittest.cc)
     32 target_link_libraries(testapp ${GTEST_LDFLAGS})
     33 target_compile_options(testapp PUBLIC ${GTEST_CFLAGS})
     34 
     35 include(CTest)
     36 add_test(first_and_only_test testapp)
     37 ```
     38 
     39 It is generally recommended that you use `target_compile_options` + `_CFLAGS`
     40 over `target_include_directories` + `_INCLUDE_DIRS` as the former includes not
     41 just -I flags (GoogleTest might require a macro indicating to internal headers
     42 that all libraries have been compiled with threading enabled. In addition,
     43 GoogleTest might also require `-pthread` in the compiling step, and as such
     44 splitting the pkg-config `Cflags` variable into include dirs and macros for
     45 `target_compile_definitions()` might still miss this). The same recommendation
     46 goes for using `_LDFLAGS` over the more commonplace `_LIBRARIES`, which
     47 happens to discard `-L` flags and `-pthread`.
     48 
     49 
     50 ### Autotools ###
     51 
     52 Finding GoogleTest in Autoconf and using it from Automake is also fairly easy:
     53 
     54 In your `configure.ac`:
     55 
     56 ```
     57 AC_PREREQ([2.69])
     58 AC_INIT([my_gtest_pkgconfig], [0.0.1])
     59 AC_CONFIG_SRCDIR([samples/sample3_unittest.cc])
     60 AC_PROG_CXX
     61 
     62 PKG_CHECK_MODULES([GTEST], [gtest_main])
     63 
     64 AM_INIT_AUTOMAKE([foreign subdir-objects])
     65 AC_CONFIG_FILES([Makefile])
     66 AC_OUTPUT
     67 ```
     68 
     69 and in your `Makefile.am`:
     70 
     71 ```
     72 check_PROGRAMS = testapp
     73 TESTS = $(check_PROGRAMS)
     74 
     75 testapp_SOURCES = samples/sample3_unittest.cc
     76 testapp_CXXFLAGS = $(GTEST_CFLAGS)
     77 testapp_LDADD = $(GTEST_LIBS)
     78 ```
     79 
     80 
     81 ### Meson ###
     82 
     83 Meson natively uses pkgconfig to query dependencies:
     84 
     85 ```
     86 project('my_gtest_pkgconfig', 'cpp', version : '0.0.1')
     87 
     88 gtest_dep = dependency('gtest_main')
     89 
     90 testapp = executable(
     91   'testapp',
     92   files(['samples/sample3_unittest.cc']),
     93   dependencies : gtest_dep,
     94   install : false)
     95 
     96 test('first_and_only_test', testapp)
     97 ```
     98 
     99 
    100 ### Plain Makefiles ###
    101 
    102 Since `pkg-config` is a small Unix command-line utility, it can be used
    103 in handwritten `Makefile`s too:
    104 
    105 ``` Makefile
    106 GTEST_CFLAGS = `pkg-config --cflags gtest_main`
    107 GTEST_LIBS = `pkg-config --libs gtest_main`
    108 
    109 .PHONY: tests all
    110 
    111 tests: all
    112 	./testapp
    113 
    114 all: testapp
    115 
    116 testapp: testapp.o
    117 	$(CXX) $(CXXFLAGS) $(LDFLAGS) $< -o $@ $(GTEST_LIBS)
    118 
    119 testapp.o: samples/sample3_unittest.cc
    120 	$(CXX) $(CPPFLAGS) $(CXXFLAGS) $< -c -o $@ $(GTEST_CFLAGS)
    121 ```
    122 
    123 
    124 ### Help! pkg-config can't find GoogleTest! ###
    125 
    126 Let's say you have a `CMakeLists.txt` along the lines of the one in this
    127 tutorial and you try to run `cmake`. It is very possible that you get a
    128 failure along the lines of:
    129 
    130 ```
    131 -- Checking for one of the modules 'gtest_main'
    132 CMake Error at /usr/share/cmake/Modules/FindPkgConfig.cmake:640 (message):
    133   None of the required 'gtest_main' found
    134 ```
    135 
    136 These failures are common if you installed GoogleTest yourself and have not
    137 sourced it from a distro or other package manager. If so, you need to tell
    138 pkg-config where it can find the `.pc` files containing the information.
    139 Say you installed GoogleTest to `/usr/local`, then it might be that the
    140 `.pc` files are installed under `/usr/local/lib64/pkgconfig`. If you set
    141 
    142 ```
    143 export PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig
    144 ```
    145 
    146 pkg-config will also try to look in `PKG_CONFIG_PATH` to find `gtest_main.pc`.
    147