| 1 |
### Generic Build Instructions |
| 2 |
|
| 3 |
#### Setup |
| 4 |
|
| 5 |
To build GoogleTest and your tests that use it, you need to tell your build |
| 6 |
system where to find its headers and source files. The exact way to do it |
| 7 |
depends on which build system you use, and is usually straightforward. |
| 8 |
|
| 9 |
### Build with CMake |
| 10 |
|
| 11 |
GoogleTest comes with a CMake build script |
| 12 |
([CMakeLists.txt](https://github.com/google/googletest/blob/master/CMakeLists.txt)) |
| 13 |
that can be used on a wide range of platforms ("C" stands for cross-platform.). |
| 14 |
If you don't have CMake installed already, you can download it for free from |
| 15 |
<http://www.cmake.org/>. |
| 16 |
|
| 17 |
CMake works by generating native makefiles or build projects that can be used in |
| 18 |
the compiler environment of your choice. You can either build GoogleTest as a |
| 19 |
standalone project or it can be incorporated into an existing CMake build for |
| 20 |
another project. |
| 21 |
|
| 22 |
#### Standalone CMake Project |
| 23 |
|
| 24 |
When building GoogleTest as a standalone project, the typical workflow starts |
| 25 |
with |
| 26 |
|
| 27 |
``` |
| 28 |
git clone https://github.com/google/googletest.git -b release-1.11.0 |
| 29 |
cd googletest # Main directory of the cloned repository. |
| 30 |
mkdir build # Create a directory to hold the build output. |
| 31 |
cd build |
| 32 |
cmake .. # Generate native build scripts for GoogleTest. |
| 33 |
``` |
| 34 |
|
| 35 |
The above command also includes GoogleMock by default. And so, if you want to |
| 36 |
build only GoogleTest, you should replace the last command with |
| 37 |
|
| 38 |
``` |
| 39 |
cmake .. -DBUILD_GMOCK=OFF |
| 40 |
``` |
| 41 |
|
| 42 |
If you are on a \*nix system, you should now see a Makefile in the current |
| 43 |
directory. Just type `make` to build GoogleTest. And then you can simply install |
| 44 |
GoogleTest if you are a system administrator. |
| 45 |
|
| 46 |
``` |
| 47 |
make |
| 48 |
sudo make install # Install in /usr/local/ by default |
| 49 |
``` |
| 50 |
|
| 51 |
If you use Windows and have Visual Studio installed, a `gtest.sln` file and |
| 52 |
several `.vcproj` files will be created. You can then build them using Visual |
| 53 |
Studio. |
| 54 |
|
| 55 |
On Mac OS X with Xcode installed, a `.xcodeproj` file will be generated. |
| 56 |
|
| 57 |
#### Incorporating Into An Existing CMake Project |
| 58 |
|
| 59 |
If you want to use GoogleTest in a project which already uses CMake, the easiest |
| 60 |
way is to get installed libraries and headers. |
| 61 |
|
| 62 |
* Import GoogleTest by using `find_package` (or `pkg_check_modules`). For |
| 63 |
example, if `find_package(GTest CONFIG REQUIRED)` succeeds, you can use the |
| 64 |
libraries as `GTest::gtest`, `GTest::gmock`. |
| 65 |
|
| 66 |
And a more robust and flexible approach is to build GoogleTest as part of that |
| 67 |
project directly. This is done by making the GoogleTest source code available to |
| 68 |
the main build and adding it using CMake's `add_subdirectory()` command. This |
| 69 |
has the significant advantage that the same compiler and linker settings are |
| 70 |
used between GoogleTest and the rest of your project, so issues associated with |
| 71 |
using incompatible libraries (eg debug/release), etc. are avoided. This is |
| 72 |
particularly useful on Windows. Making GoogleTest's source code available to the |
| 73 |
main build can be done a few different ways: |
| 74 |
|
| 75 |
* Download the GoogleTest source code manually and place it at a known |
| 76 |
location. This is the least flexible approach and can make it more difficult |
| 77 |
to use with continuous integration systems, etc. |
| 78 |
* Embed the GoogleTest source code as a direct copy in the main project's |
| 79 |
source tree. This is often the simplest approach, but is also the hardest to |
| 80 |
keep up to date. Some organizations may not permit this method. |
| 81 |
* Add GoogleTest as a git submodule or equivalent. This may not always be |
| 82 |
possible or appropriate. Git submodules, for example, have their own set of |
| 83 |
advantages and drawbacks. |
| 84 |
* Use CMake to download GoogleTest as part of the build's configure step. This |
| 85 |
approach doesn't have the limitations of the other methods. |
| 86 |
|
| 87 |
The last of the above methods is implemented with a small piece of CMake code |
| 88 |
that downloads and pulls the GoogleTest code into the main build. |
| 89 |
|
| 90 |
Just add to your `CMakeLists.txt`: |
| 91 |
|
| 92 |
```cmake |
| 93 |
include(FetchContent) |
| 94 |
FetchContent_Declare( |
| 95 |
googletest |
| 96 |
# Specify the commit you depend on and update it regularly. |
| 97 |
URL https://github.com/google/googletest/archive/609281088cfefc76f9d0ce82e1ff6c30cc3591e5.zip |
| 98 |
) |
| 99 |
# For Windows: Prevent overriding the parent project's compiler/linker settings |
| 100 |
set(gtest_force_shared_crt ON CACHE BOOL "" FORCE) |
| 101 |
FetchContent_MakeAvailable(googletest) |
| 102 |
|
| 103 |
# Now simply link against gtest or gtest_main as needed. Eg |
| 104 |
add_executable(example example.cpp) |
| 105 |
target_link_libraries(example gtest_main) |
| 106 |
add_test(NAME example_test COMMAND example) |
| 107 |
``` |
| 108 |
|
| 109 |
Note that this approach requires CMake 3.14 or later due to its use of the |
| 110 |
`FetchContent_MakeAvailable()` command. |
| 111 |
|
| 112 |
##### Visual Studio Dynamic vs Static Runtimes |
| 113 |
|
| 114 |
By default, new Visual Studio projects link the C runtimes dynamically but |
| 115 |
GoogleTest links them statically. This will generate an error that looks |
| 116 |
something like the following: gtest.lib(gtest-all.obj) : error LNK2038: mismatch |
| 117 |
detected for 'RuntimeLibrary': value 'MTd_StaticDebug' doesn't match value |
| 118 |
'MDd_DynamicDebug' in main.obj |
| 119 |
|
| 120 |
GoogleTest already has a CMake option for this: `gtest_force_shared_crt` |
| 121 |
|
| 122 |
Enabling this option will make gtest link the runtimes dynamically too, and |
| 123 |
match the project in which it is included. |
| 124 |
|
| 125 |
#### C++ Standard Version |
| 126 |
|
| 127 |
An environment that supports C++11 is required in order to successfully build |
| 128 |
GoogleTest. One way to ensure this is to specify the standard in the top-level |
| 129 |
project, for example by using the `set(CMAKE_CXX_STANDARD 11)` command. If this |
| 130 |
is not feasible, for example in a C project using GoogleTest for validation, |
| 131 |
then it can be specified by adding it to the options for cmake via the |
| 132 |
`DCMAKE_CXX_FLAGS` option. |
| 133 |
|
| 134 |
### Tweaking GoogleTest |
| 135 |
|
| 136 |
GoogleTest can be used in diverse environments. The default configuration may |
| 137 |
not work (or may not work well) out of the box in some environments. However, |
| 138 |
you can easily tweak GoogleTest by defining control macros on the compiler |
| 139 |
command line. Generally, these macros are named like `GTEST_XYZ` and you define |
| 140 |
them to either 1 or 0 to enable or disable a certain feature. |
| 141 |
|
| 142 |
We list the most frequently used macros below. For a complete list, see file |
| 143 |
[include/gtest/internal/gtest-port.h](https://github.com/google/googletest/blob/master/googletest/include/gtest/internal/gtest-port.h). |
| 144 |
|
| 145 |
### Multi-threaded Tests |
| 146 |
|
| 147 |
GoogleTest is thread-safe where the pthread library is available. After |
| 148 |
`#include "gtest/gtest.h"`, you can check the |
| 149 |
`GTEST_IS_THREADSAFE` macro to see whether this is the case (yes if the macro is |
| 150 |
`#defined` to 1, no if it's undefined.). |
| 151 |
|
| 152 |
If GoogleTest doesn't correctly detect whether pthread is available in your |
| 153 |
environment, you can force it with |
| 154 |
|
| 155 |
-DGTEST_HAS_PTHREAD=1 |
| 156 |
|
| 157 |
or |
| 158 |
|
| 159 |
-DGTEST_HAS_PTHREAD=0 |
| 160 |
|
| 161 |
When GoogleTest uses pthread, you may need to add flags to your compiler and/or |
| 162 |
linker to select the pthread library, or you'll get link errors. If you use the |
| 163 |
CMake script, this is taken care of for you. If you use your own build script, |
| 164 |
you'll need to read your compiler and linker's manual to figure out what flags |
| 165 |
to add. |
| 166 |
|
| 167 |
### As a Shared Library (DLL) |
| 168 |
|
| 169 |
GoogleTest is compact, so most users can build and link it as a static library |
| 170 |
for the simplicity. You can choose to use GoogleTest as a shared library (known |
| 171 |
as a DLL on Windows) if you prefer. |
| 172 |
|
| 173 |
To compile *gtest* as a shared library, add |
| 174 |
|
| 175 |
-DGTEST_CREATE_SHARED_LIBRARY=1 |
| 176 |
|
| 177 |
to the compiler flags. You'll also need to tell the linker to produce a shared |
| 178 |
library instead - consult your linker's manual for how to do it. |
| 179 |
|
| 180 |
To compile your *tests* that use the gtest shared library, add |
| 181 |
|
| 182 |
-DGTEST_LINKED_AS_SHARED_LIBRARY=1 |
| 183 |
|
| 184 |
to the compiler flags. |
| 185 |
|
| 186 |
Note: while the above steps aren't technically necessary today when using some |
| 187 |
compilers (e.g. GCC), they may become necessary in the future, if we decide to |
| 188 |
improve the speed of loading the library (see |
| 189 |
<http://gcc.gnu.org/wiki/Visibility> for details). Therefore you are recommended |
| 190 |
to always add the above flags when using GoogleTest as a shared library. |
| 191 |
Otherwise a future release of GoogleTest may break your build script. |
| 192 |
|
| 193 |
### Avoiding Macro Name Clashes |
| 194 |
|
| 195 |
In C++, macros don't obey namespaces. Therefore two libraries that both define a |
| 196 |
macro of the same name will clash if you `#include` both definitions. In case a |
| 197 |
GoogleTest macro clashes with another library, you can force GoogleTest to |
| 198 |
rename its macro to avoid the conflict. |
| 199 |
|
| 200 |
Specifically, if both GoogleTest and some other code define macro FOO, you can |
| 201 |
add |
| 202 |
|
| 203 |
-DGTEST_DONT_DEFINE_FOO=1 |
| 204 |
|
| 205 |
to the compiler flags to tell GoogleTest to change the macro's name from `FOO` |
| 206 |
to `GTEST_FOO`. Currently `FOO` can be `ASSERT_EQ`, `ASSERT_FALSE`, `ASSERT_GE`, |
| 207 |
`ASSERT_GT`, `ASSERT_LE`, `ASSERT_LT`, `ASSERT_NE`, `ASSERT_TRUE`, |
| 208 |
`EXPECT_FALSE`, `EXPECT_TRUE`, `FAIL`, `SUCCEED`, `TEST`, or `TEST_F`. For |
| 209 |
example, with `-DGTEST_DONT_DEFINE_TEST=1`, you'll need to write |
| 210 |
|
| 211 |
GTEST_TEST(SomeTest, DoesThis) { ... } |
| 212 |
|
| 213 |
instead of |
| 214 |
|
| 215 |
TEST(SomeTest, DoesThis) { ... } |
| 216 |
|
| 217 |
in order to define a test. |