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 all
  14 examples here we assume you want to compile the sample
  15 `samples/sample3_unittest.cc`.
  16
  17 ### CMake
  18
  19 Using `pkg-config` in CMake is fairly easy:
  20
  21 ```cmake
  22 cmake_minimum_required(VERSION 3.0)
  23
  24 cmake_policy(SET CMP0048 NEW)
  25 project(my_gtest_pkgconfig VERSION 0.0.1 LANGUAGES CXX)
  26
  27 find_package(PkgConfig)
  28 pkg_search_module(GTEST REQUIRED gtest_main)
  29
  30 add_executable(testapp samples/sample3_unittest.cc)
  31 target_link_libraries(testapp ${GTEST_LDFLAGS})
  32 target_compile_options(testapp PUBLIC ${GTEST_CFLAGS})
  33
  34 include(CTest)
  35 add_test(first_and_only_test testapp)
  36 ```
  37
  38 It is generally recommended that you use `target_compile_options` + `_CFLAGS`
  39 over `target_include_directories` + `_INCLUDE_DIRS` as the former includes not
  40 just -I flags (GoogleTest might require a macro indicating to internal headers
  41 that all libraries have been compiled with threading enabled. In addition,
  42 GoogleTest might also require `-pthread` in the compiling step, and as such
  43 splitting the pkg-config `Cflags` variable into include dirs and macros for
  44 `target_compile_definitions()` might still miss this). The same recommendation
  45 goes for using `_LDFLAGS` over the more commonplace `_LIBRARIES`, which happens
  46 to discard `-L` flags and `-pthread`.
  47
  48 ### Help! pkg-config can't find GoogleTest!
  49
  50 Let's say you have a `CMakeLists.txt` along the lines of the one in this
  51 tutorial and you try to run `cmake`. It is very possible that you get a failure
  52 along the lines of:
  53
  54 ```
  55 -- Checking for one of the modules 'gtest_main'
  56 CMake Error at /usr/share/cmake/Modules/FindPkgConfig.cmake:640 (message):
  57   None of the required 'gtest_main' found
  58 ```
  59
  60 These failures are common if you installed GoogleTest yourself and have not
  61 sourced it from a distro or other package manager. If so, you need to tell
  62 pkg-config where it can find the `.pc` files containing the information. Say you
  63 installed GoogleTest to `/usr/local`, then it might be that the `.pc` files are
  64 installed under `/usr/local/lib64/pkgconfig`. If you set
  65
  66 ```
  67 export PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig
  68 ```
  69
  70 pkg-config will also try to look in `PKG_CONFIG_PATH` to find `gtest_main.pc`.
  71
  72 ### Using pkg-config in a cross-compilation setting
  73
  74 Pkg-config can be used in a cross-compilation setting too. To do this, let's
  75 assume the final prefix of the cross-compiled installation will be `/usr`, and
  76 your sysroot is `/home/MYUSER/sysroot`. Configure and install GTest using
  77
  78 ```
  79 mkdir build && cmake -DCMAKE_INSTALL_PREFIX=/usr ..
  80 ```
  81
  82 Install into the sysroot using `DESTDIR`:
  83
  84 ```
  85 make -j install DESTDIR=/home/MYUSER/sysroot
  86 ```
  87
  88 Before we continue, it is recommended to **always** define the following two
  89 variables for pkg-config in a cross-compilation setting:
  90
  91 ```
  92 export PKG_CONFIG_ALLOW_SYSTEM_CFLAGS=yes
  93 export PKG_CONFIG_ALLOW_SYSTEM_LIBS=yes
  94 ```
  95
  96 otherwise `pkg-config` will filter `-I` and `-L` flags against standard prefixes
  97 such as `/usr` (see https://bugs.freedesktop.org/show_bug.cgi?id=28264#c3 for
  98 reasons why this stripping needs to occur usually).
  99
 100 If you look at the generated pkg-config file, it will look something like
 101
 102 ```
 103 libdir=/usr/lib64
 104 includedir=/usr/include
 105
 106 Name: gtest
 107 Description: GoogleTest (without main() function)
 108 Version: 1.10.0
 109 URL: https://github.com/google/googletest
 110 Libs: -L${libdir} -lgtest -lpthread
 111 Cflags: -I${includedir} -DGTEST_HAS_PTHREAD=1 -lpthread
 112 ```
 113
 114 Notice that the sysroot is not included in `libdir` and `includedir`! If you try
 115 to run `pkg-config` with the correct
 116 `PKG_CONFIG_LIBDIR=/home/MYUSER/sysroot/usr/lib64/pkgconfig` against this `.pc`
 117 file, you will get
 118
 119 ```
 120 $ pkg-config --cflags gtest
 121 -DGTEST_HAS_PTHREAD=1 -lpthread -I/usr/include
 122 $ pkg-config --libs gtest
 123 -L/usr/lib64 -lgtest -lpthread
 124 ```
 125
 126 which is obviously wrong and points to the `CBUILD` and not `CHOST` root. In
 127 order to use this in a cross-compilation setting, we need to tell pkg-config to
 128 inject the actual sysroot into `-I` and `-L` variables. Let us now tell
 129 pkg-config about the actual sysroot
 130
 131 ```
 132 export PKG_CONFIG_DIR=
 133 export PKG_CONFIG_SYSROOT_DIR=/home/MYUSER/sysroot
 134 export PKG_CONFIG_LIBDIR=${PKG_CONFIG_SYSROOT_DIR}/usr/lib64/pkgconfig
 135 ```
 136
 137 and running `pkg-config` again we get
 138
 139 ```
 140 $ pkg-config --cflags gtest
 141 -DGTEST_HAS_PTHREAD=1 -lpthread -I/home/MYUSER/sysroot/usr/include
 142 $ pkg-config --libs gtest
 143 -L/home/MYUSER/sysroot/usr/lib64 -lgtest -lpthread
 144 ```
 145
 146 which contains the correct sysroot now. For a more comprehensive guide to also
 147 including `${CHOST}` in build system calls, see the excellent tutorial by Diego
 148 Elio Pettenò: <https://autotools.io/pkgconfig/cross-compiling.html>