1 2 ### Generic Build Instructions ### 3 4 #### Setup #### 5 6 To build Google Test and your tests that use it, you need to tell your 7 build system where to find its headers and source files. The exact 8 way to do it depends on which build system you use, and is usually 9 straightforward. 10 11 #### Build #### 12 13 Suppose you put Google Test in directory `${GTEST_DIR}`. To build it, 14 create a library build target (or a project as called by Visual Studio 15 and Xcode) to compile 16 17 ${GTEST_DIR}/src/gtest-all.cc 18 19 with `${GTEST_DIR}/include` in the system header search path and `${GTEST_DIR}` 20 in the normal header search path. Assuming a Linux-like system and gcc, 21 something like the following will do: 22 23 g++ -isystem ${GTEST_DIR}/include -I${GTEST_DIR} \ 24 -pthread -c ${GTEST_DIR}/src/gtest-all.cc 25 ar -rv libgtest.a gtest-all.o 26 27 (We need `-pthread` as Google Test uses threads.) 28 29 Next, you should compile your test source file with 30 `${GTEST_DIR}/include` in the system header search path, and link it 31 with gtest and any other necessary libraries: 32 33 g++ -isystem ${GTEST_DIR}/include -pthread path/to/your_test.cc libgtest.a \ 34 -o your_test 35 36 As an example, the make/ directory contains a Makefile that you can 37 use to build Google Test on systems where GNU make is available 38 (e.g. Linux, Mac OS X, and Cygwin). It doesn't try to build Google 39 Test's own tests. Instead, it just builds the Google Test library and 40 a sample test. You can use it as a starting point for your own build 41 script. 42 43 If the default settings are correct for your environment, the 44 following commands should succeed: 45 46 cd ${GTEST_DIR}/make 47 make 48 ./sample1_unittest 49 50 If you see errors, try to tweak the contents of `make/Makefile` to make 51 them go away. There are instructions in `make/Makefile` on how to do 52 it. 53 54 ### Using CMake ### 55 56 Google Test comes with a CMake build script ( 57 [CMakeLists.txt](CMakeLists.txt)) that can be used on a wide range of platforms ("C" stands for 58 cross-platform.). If you don't have CMake installed already, you can 59 download it for free from <http://www.cmake.org/>. 60 61 CMake works by generating native makefiles or build projects that can 62 be used in the compiler environment of your choice. You can either 63 build Google Test as a standalone project or it can be incorporated 64 into an existing CMake build for another project. 65 66 #### Standalone CMake Project #### 67 68 When building Google Test as a standalone project, the typical 69 workflow starts with: 70 71 mkdir mybuild # Create a directory to hold the build output. 72 cd mybuild 73 cmake ${GTEST_DIR} # Generate native build scripts. 74 75 If you want to build Google Test's samples, you should replace the 76 last command with 77 78 cmake -Dgtest_build_samples=ON ${GTEST_DIR} 79 80 If you are on a \*nix system, you should now see a Makefile in the 81 current directory. Just type 'make' to build gtest. 82 83 If you use Windows and have Visual Studio installed, a `gtest.sln` file 84 and several `.vcproj` files will be created. You can then build them 85 using Visual Studio. 86 87 On Mac OS X with Xcode installed, a `.xcodeproj` file will be generated. 88 89 #### Incorporating Into An Existing CMake Project #### 90 91 If you want to use gtest in a project which already uses CMake, then a 92 more robust and flexible approach is to build gtest as part of that 93 project directly. This is done by making the GoogleTest source code 94 available to the main build and adding it using CMake's 95 `add_subdirectory()` command. This has the significant advantage that 96 the same compiler and linker settings are used between gtest and the 97 rest of your project, so issues associated with using incompatible 98 libraries (eg debug/release), etc. are avoided. This is particularly 99 useful on Windows. Making GoogleTest's source code available to the 100 main build can be done a few different ways: 101 102 * Download the GoogleTest source code manually and place it at a 103 known location. This is the least flexible approach and can make 104 it more difficult to use with continuous integration systems, etc. 105 * Embed the GoogleTest source code as a direct copy in the main 106 project's source tree. This is often the simplest approach, but is 107 also the hardest to keep up to date. Some organizations may not 108 permit this method. 109 * Add GoogleTest as a git submodule or equivalent. This may not 110 always be possible or appropriate. Git submodules, for example, 111 have their own set of advantages and drawbacks. 112 * Use CMake to download GoogleTest as part of the build's configure 113 step. This is just a little more complex, but doesn't have the 114 limitations of the other methods. 115 116 The last of the above methods is implemented with a small piece 117 of CMake code in a separate file (e.g. `CMakeLists.txt.in`) which 118 is copied to the build area and then invoked as a sub-build 119 _during the CMake stage_. That directory is then pulled into the 120 main build with `add_subdirectory()`. For example: 121 122 New file `CMakeLists.txt.in`: 123 124 cmake_minimum_required(VERSION 2.8.2) 125 126 project(googletest-download NONE) 127 128 include(ExternalProject) 129 ExternalProject_Add(googletest 130 GIT_REPOSITORY https://github.com/google/googletest.git 131 GIT_TAG master 132 SOURCE_DIR "${CMAKE_BINARY_DIR}/googletest-src" 133 BINARY_DIR "${CMAKE_BINARY_DIR}/googletest-build" 134 CONFIGURE_COMMAND "" 135 BUILD_COMMAND "" 136 INSTALL_COMMAND "" 137 TEST_COMMAND "" 138 ) 139 140 Existing build's `CMakeLists.txt`: 141 142 # Download and unpack googletest at configure time 143 configure_file(CMakeLists.txt.in googletest-download/CMakeLists.txt) 144 execute_process(COMMAND ${CMAKE_COMMAND} -G "${CMAKE_GENERATOR}" . 145 RESULT_VARIABLE result 146 WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/googletest-download ) 147 if(result) 148 message(FATAL_ERROR "CMake step for googletest failed: ${result}") 149 endif() 150 execute_process(COMMAND ${CMAKE_COMMAND} --build . 151 RESULT_VARIABLE result 152 WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/googletest-download ) 153 if(result) 154 message(FATAL_ERROR "Build step for googletest failed: ${result}") 155 endif() 156 157 # Prevent overriding the parent project's compiler/linker 158 # settings on Windows 159 set(gtest_force_shared_crt ON CACHE BOOL "" FORCE) 160 161 # Add googletest directly to our build. This defines 162 # the gtest and gtest_main targets. 163 add_subdirectory(${CMAKE_BINARY_DIR}/googletest-src 164 ${CMAKE_BINARY_DIR}/googletest-build) 165 166 # The gtest/gtest_main targets carry header search path 167 # dependencies automatically when using CMake 2.8.11 or 168 # later. Otherwise we have to add them here ourselves. 169 if (CMAKE_VERSION VERSION_LESS 2.8.11) 170 include_directories("${gtest_SOURCE_DIR}/include") 171 endif() 172 173 # Now simply link against gtest or gtest_main as needed. Eg 174 add_executable(example example.cpp) 175 target_link_libraries(example gtest_main) 176 add_test(NAME example_test COMMAND example) 177 178 Note that this approach requires CMake 2.8.2 or later due to 179 its use of the `ExternalProject_Add()` command. The above 180 technique is discussed in more detail in 181 [this separate article](http://crascit.com/2015/07/25/cmake-gtest/) 182 which also contains a link to a fully generalized implementation 183 of the technique. 184 185 186 ### Legacy Build Scripts ### 187 188 Before settling on CMake, we have been providing hand-maintained build 189 projects/scripts for Visual Studio, Xcode, and Autotools. While we 190 continue to provide them for convenience, they are not actively 191 maintained any more. We highly recommend that you follow the 192 instructions in the above sections to integrate Google Test 193 with your existing build system. 194 195 If you still need to use the legacy build scripts, here's how: 196 197 The msvc\ folder contains two solutions with Visual C++ projects. 198 Open the `gtest.sln` or `gtest-md.sln` file using Visual Studio, and you 199 are ready to build Google Test the same way you build any Visual 200 Studio project. Files that have names ending with -md use DLL 201 versions of Microsoft runtime libraries (the /MD or the /MDd compiler 202 option). Files without that suffix use static versions of the runtime 203 libraries (the /MT or the /MTd option). Please note that one must use 204 the same option to compile both gtest and the test code. If you use 205 Visual Studio 2005 or above, we recommend the -md version as /MD is 206 the default for new projects in these versions of Visual Studio. 207 208 On Mac OS X, open the `gtest.xcodeproj` in the `xcode/` folder using 209 Xcode. Build the "gtest" target. The universal binary framework will 210 end up in your selected build directory (selected in the Xcode 211 "Preferences..." -> "Building" pane and defaults to xcode/build). 212 Alternatively, at the command line, enter: 213 214 xcodebuild 215 216 This will build the "Release" configuration of gtest.framework in your 217 default build location. See the "xcodebuild" man page for more 218 information about building different configurations and building in 219 different locations. 220 221 If you wish to use the Google Test Xcode project with Xcode 4.x and 222 above, you need to either: 223 224 * update the SDK configuration options in xcode/Config/General.xconfig. 225 Comment options `SDKROOT`, `MACOS_DEPLOYMENT_TARGET`, and `GCC_VERSION`. If 226 you choose this route you lose the ability to target earlier versions 227 of MacOS X. 228 * Install an SDK for an earlier version. This doesn't appear to be 229 supported by Apple, but has been reported to work 230 (http://stackoverflow.com/questions/5378518). 231 232 ### Tweaking Google Test ### 233 234 Google Test can be used in diverse environments. The default 235 configuration may not work (or may not work well) out of the box in 236 some environments. However, you can easily tweak Google Test by 237 defining control macros on the compiler command line. Generally, 238 these macros are named like `GTEST_XYZ` and you define them to either 1 239 or 0 to enable or disable a certain feature. 240 241 We list the most frequently used macros below. For a complete list, 242 see file [include/gtest/internal/gtest-port.h](include/gtest/internal/gtest-port.h). 243 244 ### Choosing a TR1 Tuple Library ### 245 246 Some Google Test features require the C++ Technical Report 1 (TR1) 247 tuple library, which is not yet available with all compilers. The 248 good news is that Google Test implements a subset of TR1 tuple that's 249 enough for its own need, and will automatically use this when the 250 compiler doesn't provide TR1 tuple. 251 252 Usually you don't need to care about which tuple library Google Test 253 uses. However, if your project already uses TR1 tuple, you need to 254 tell Google Test to use the same TR1 tuple library the rest of your 255 project uses, or the two tuple implementations will clash. To do 256 that, add 257 258 -DGTEST_USE_OWN_TR1_TUPLE=0 259 260 to the compiler flags while compiling Google Test and your tests. If 261 you want to force Google Test to use its own tuple library, just add 262 263 -DGTEST_USE_OWN_TR1_TUPLE=1 264 265 to the compiler flags instead. 266 267 If you don't want Google Test to use tuple at all, add 268 269 -DGTEST_HAS_TR1_TUPLE=0 270 271 and all features using tuple will be disabled. 272 273 ### Multi-threaded Tests ### 274 275 Google Test is thread-safe where the pthread library is available. 276 After `#include "gtest/gtest.h"`, you can check the `GTEST_IS_THREADSAFE` 277 macro to see whether this is the case (yes if the macro is `#defined` to 278 1, no if it's undefined.). 279 280 If Google Test doesn't correctly detect whether pthread is available 281 in your environment, you can force it with 282 283 -DGTEST_HAS_PTHREAD=1 284 285 or 286 287 -DGTEST_HAS_PTHREAD=0 288 289 When Google Test uses pthread, you may need to add flags to your 290 compiler and/or linker to select the pthread library, or you'll get 291 link errors. If you use the CMake script or the deprecated Autotools 292 script, this is taken care of for you. If you use your own build 293 script, you'll need to read your compiler and linker's manual to 294 figure out what flags to add. 295 296 ### As a Shared Library (DLL) ### 297 298 Google Test is compact, so most users can build and link it as a 299 static library for the simplicity. You can choose to use Google Test 300 as a shared library (known as a DLL on Windows) if you prefer. 301 302 To compile *gtest* as a shared library, add 303 304 -DGTEST_CREATE_SHARED_LIBRARY=1 305 306 to the compiler flags. You'll also need to tell the linker to produce 307 a shared library instead - consult your linker's manual for how to do 308 it. 309 310 To compile your *tests* that use the gtest shared library, add 311 312 -DGTEST_LINKED_AS_SHARED_LIBRARY=1 313 314 to the compiler flags. 315 316 Note: while the above steps aren't technically necessary today when 317 using some compilers (e.g. GCC), they may become necessary in the 318 future, if we decide to improve the speed of loading the library (see 319 <http://gcc.gnu.org/wiki/Visibility> for details). Therefore you are 320 recommended to always add the above flags when using Google Test as a 321 shared library. Otherwise a future release of Google Test may break 322 your build script. 323 324 ### Avoiding Macro Name Clashes ### 325 326 In C++, macros don't obey namespaces. Therefore two libraries that 327 both define a macro of the same name will clash if you `#include` both 328 definitions. In case a Google Test macro clashes with another 329 library, you can force Google Test to rename its macro to avoid the 330 conflict. 331 332 Specifically, if both Google Test and some other code define macro 333 FOO, you can add 334 335 -DGTEST_DONT_DEFINE_FOO=1 336 337 to the compiler flags to tell Google Test to change the macro's name 338 from `FOO` to `GTEST_FOO`. Currently `FOO` can be `FAIL`, `SUCCEED`, 339 or `TEST`. For example, with `-DGTEST_DONT_DEFINE_TEST=1`, you'll 340 need to write 341 342 GTEST_TEST(SomeTest, DoesThis) { ... } 343 344 instead of 345 346 TEST(SomeTest, DoesThis) { ... } 347 348 in order to define a test. 349 350 ## Developing Google Test ## 351 352 This section discusses how to make your own changes to Google Test. 353 354 ### Testing Google Test Itself ### 355 356 To make sure your changes work as intended and don't break existing 357 functionality, you'll want to compile and run Google Test's own tests. 358 For that you can use CMake: 359 360 mkdir mybuild 361 cd mybuild 362 cmake -Dgtest_build_tests=ON ${GTEST_DIR} 363 364 Make sure you have Python installed, as some of Google Test's tests 365 are written in Python. If the cmake command complains about not being 366 able to find Python (`Could NOT find PythonInterp (missing: 367 PYTHON_EXECUTABLE)`), try telling it explicitly where your Python 368 executable can be found: 369 370 cmake -DPYTHON_EXECUTABLE=path/to/python -Dgtest_build_tests=ON ${GTEST_DIR} 371 372 Next, you can build Google Test and all of its own tests. On \*nix, 373 this is usually done by 'make'. To run the tests, do 374 375 make test 376 377 All tests should pass. 378 379 Normally you don't need to worry about regenerating the source files, 380 unless you need to modify them. In that case, you should modify the 381 corresponding .pump files instead and run the pump.py Python script to 382 regenerate them. You can find pump.py in the [scripts/](scripts/) directory. 383 Read the [Pump manual](docs/PumpManual.md) for how to use it. 384
