contrib/googletest/googletest/docs/Pkgconfig.md

   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 ```
  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 ```
 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`.