Skip to content
Permalink
Browse files

Add documentation for pkg-config

  • Loading branch information...
SoapGentoo committed Aug 14, 2017
1 parent 8604c4a commit 9cacce4e5ca01f2c15775cf5e59297a7b422cd8b
Showing with 152 additions and 0 deletions.
  1. +6 −0 googletest/docs/FAQ.md
  2. +146 −0 googletest/docs/Pkgconfig.md
@@ -1060,6 +1060,12 @@ TEST_F(CoolTest, DoSomething) {
If you try to build Google Test's Xcode project with Xcode 4.0 or later, you may encounter an error message that looks like
"Missing SDK in target gtest\_framework: /Developer/SDKs/MacOSX10.4u.sdk". That means that Xcode does not support the SDK the project is targeting. See the Xcode section in the [README](../README.md) file on how to resolve this.

## How do I easily discover the flags needed for GoogleTest? ##

GoogleTest (and GoogleMock) now support discovering all necessary flags using pkg-config.
See the [pkg-config guide](Pkgconfig.md) on how you can easily discover all compiler and
linker flags using pkg-config.

## My question is not covered in your FAQ! ##

If you cannot find the answer to your question in this FAQ, there are
@@ -0,0 +1,146 @@
## Using GoogleTest from various build systems ##

GoogleTest comes with pkg-config files that can be used to determine all
necessary flags for compiling and linking to GoogleTest (and GoogleMock).
Pkg-config is a standardised plain-text format containing

* the includedir (-I) path
* necessary macro (-D) definitions
* further required flags (-pthread)
* the library (-L) path
* the library (-l) to link to

All current build systems support pkg-config in one way or another. For
all examples here we assume you want to compile the sample
`samples/sample3_unittest.cc`.


### CMake ###

Using `pkg-config` in CMake is fairly easy:

```
cmake_minimum_required(VERSION 3.0)
cmake_policy(SET CMP0048 NEW)
project(my_gtest_pkgconfig VERSION 0.0.1 LANGUAGES CXX)
find_package(PkgConfig)
pkg_search_module(GTEST REQUIRED gtest_main)
add_executable(testapp samples/sample3_unittest.cc)
target_link_libraries(testapp ${GTEST_LDFLAGS})
target_compile_options(testapp PUBLIC ${GTEST_CFLAGS})
include(CTest)
add_test(first_and_only_test testapp)
```

It is generally recommended that you use `target_compile_options` + `_CFLAGS`
over `target_include_directories` + `_INCLUDE_DIRS` as the former includes not
just -I flags (GoogleTest might require a macro indicating to internal headers
that all libraries have been compiled with threading enabled. In addition,
GoogleTest might also require `-pthread` in the compiling step, and as such
splitting the pkg-config `Cflags` variable into include dirs and macros for
`target_compile_definitions()` might still miss this). The same recommendation
goes for using `_LDFLAGS` over the more commonplace `_LIBRARIES`, which
happens to discard `-L` flags and `-pthread`.


### Autotools ###

Finding GoogleTest in Autoconf and using it from Automake is also fairly easy:

In your `configure.ac`:

```
AC_PREREQ([2.69])
AC_INIT([my_gtest_pkgconfig], [0.0.1])
AC_CONFIG_SRCDIR([samples/sample3_unittest.cc])
AC_PROG_CXX
PKG_CHECK_MODULES([GTEST], [gtest_main])
AM_INIT_AUTOMAKE([foreign subdir-objects])
AC_CONFIG_FILES([Makefile])
AC_OUTPUT
```

and in your `Makefile.am`:

```
check_PROGRAMS = testapp
TESTS = $(check_PROGRAMS)
testapp_SOURCES = samples/sample3_unittest.cc
testapp_CXXFLAGS = $(GTEST_CFLAGS)
testapp_LDADD = $(GTEST_LIBS)
```


### Meson ###

Meson natively uses pkgconfig to query dependencies:

```
project('my_gtest_pkgconfig', 'cpp', version : '0.0.1')
gtest_dep = dependency('gtest_main')
testapp = executable(
'testapp',
files(['samples/sample3_unittest.cc']),
dependencies : gtest_dep,
install : false)
test('first_and_only_test', testapp)
```


### Plain Makefiles ###

Since `pkg-config` is a small Unix command-line utility, it can be used
in handwritten `Makefile`s too:

```
GTEST_CFLAGS = `pkg-config --cflags gtest_main`
GTEST_LIBS = `pkg-config --libs gtest_main`
.PHONY: tests all
tests: all
./testapp
all: testapp
testapp: testapp.o
$(CXX) $(CXXFLAGS) $(LDFLAGS) $< -o $@ $(GTEST_LIBS)
testapp.o: samples/sample3_unittest.cc
$(CXX) $(CPPFLAGS) $(CXXFLAGS) $< -c -o $@ $(GTEST_CFLAGS)
```


### Help! pkg-config can't find GoogleTest! ###

Let's say you have a `CMakeLists.txt` along the lines of the one in this
tutorial and you try to run `cmake`. It is very possible that you get a
failure along the lines of:

```
-- Checking for one of the modules 'gtest_main'
CMake Error at /usr/share/cmake/Modules/FindPkgConfig.cmake:640 (message):
None of the required 'gtest_main' found
```

These failures are common if you installed GoogleTest yourself and have not
sourced it from a distro or other package manager. If so, you need to tell
pkg-config where it can find the `.pc` files containing the information.
Say you installed GoogleTest to `/usr/local`, then it might be that the
`.pc` files are installed under `/usr/local/lib64/pkgconfig`. If you set

```
export PKG_CONFIG_PATH=/usr/local/lib64/pkgconfig
```

pkg-config will also try to look in `PKG_CONFIG_PATH` to find `gtest_main.pc`.

0 comments on commit 9cacce4

Please sign in to comment.
You can’t perform that action at this time.