2 ### Generic Build Instructions ###
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
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
17 ${GTEST_DIR}/src/gtest-all.cc
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:
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
27 (We need `-pthread` as Google Test uses threads.)
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:
33 g++ -isystem ${GTEST_DIR}/include -pthread path/to/your_test.cc libgtest.a \
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
43 If the default settings are correct for your environment, the
44 following commands should succeed:
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
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/>.
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.
66 #### Standalone CMake Project ####
68 When building Google Test as a standalone project, the typical
71 mkdir mybuild # Create a directory to hold the build output.
73 cmake ${GTEST_DIR} # Generate native build scripts.
75 If you want to build Google Test's samples, you should replace the
78 cmake -Dgtest_build_samples=ON ${GTEST_DIR}
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.
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
87 On Mac OS X with Xcode installed, a `.xcodeproj` file will be generated.
89 #### Incorporating Into An Existing CMake Project ####
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:
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
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.
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:
122 New file `CMakeLists.txt.in`:
124 cmake_minimum_required(VERSION 2.8.2)
126 project(googletest-download NONE)
128 include(ExternalProject)
129 ExternalProject_Add(googletest
130 GIT_REPOSITORY https://github.com/google/googletest.git
132 SOURCE_DIR "${CMAKE_BINARY_DIR}/googletest-src"
133 BINARY_DIR "${CMAKE_BINARY_DIR}/googletest-build"
140 Existing build's `CMakeLists.txt`:
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 )
148 message(FATAL_ERROR "CMake step for googletest failed: ${result}")
150 execute_process(COMMAND ${CMAKE_COMMAND} --build .
151 RESULT_VARIABLE result
152 WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/googletest-download )
154 message(FATAL_ERROR "Build step for googletest failed: ${result}")
157 # Prevent overriding the parent project's compiler/linker
158 # settings on Windows
159 set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
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
167 # The gtest/gtest_main targets carry header search path
168 # dependencies automatically when using CMake 2.8.11 or
169 # later. Otherwise we have to add them here ourselves.
170 if (CMAKE_VERSION VERSION_LESS 2.8.11)
171 include_directories("${gtest_SOURCE_DIR}/include")
174 # Now simply link against gtest or gtest_main as needed. Eg
175 add_executable(example example.cpp)
176 target_link_libraries(example gtest_main)
177 add_test(NAME example_test COMMAND example)
179 Note that this approach requires CMake 2.8.2 or later due to
180 its use of the `ExternalProject_Add()` command. The above
181 technique is discussed in more detail in
182 [this separate article](http://crascit.com/2015/07/25/cmake-gtest/)
183 which also contains a link to a fully generalized implementation
186 ##### Visual Studio Dynamic vs Static Runtimes #####
188 By default, new Visual Studio projects link the C runtimes dynamically
189 but Google Test links them statically.
190 This will generate an error that looks something like the following:
191 gtest.lib(gtest-all.obj) : error LNK2038: mismatch detected for 'RuntimeLibrary': value 'MTd_StaticDebug' doesn't match value 'MDd_DynamicDebug' in main.obj
193 Google Test already has a CMake option for this: `gtest_force_shared_crt`
195 Enabling this option will make gtest link the runtimes dynamically too,
196 and match the project in which it is included.
198 ### Legacy Build Scripts ###
200 Before settling on CMake, we have been providing hand-maintained build
201 projects/scripts for Visual Studio, Xcode, and Autotools. While we
202 continue to provide them for convenience, they are not actively
203 maintained any more. We highly recommend that you follow the
204 instructions in the above sections to integrate Google Test
205 with your existing build system.
207 If you still need to use the legacy build scripts, here's how:
209 The msvc\ folder contains two solutions with Visual C++ projects.
210 Open the `gtest.sln` or `gtest-md.sln` file using Visual Studio, and you
211 are ready to build Google Test the same way you build any Visual
212 Studio project. Files that have names ending with -md use DLL
213 versions of Microsoft runtime libraries (the /MD or the /MDd compiler
214 option). Files without that suffix use static versions of the runtime
215 libraries (the /MT or the /MTd option). Please note that one must use
216 the same option to compile both gtest and the test code. If you use
217 Visual Studio 2005 or above, we recommend the -md version as /MD is
218 the default for new projects in these versions of Visual Studio.
220 On Mac OS X, open the `gtest.xcodeproj` in the `xcode/` folder using
221 Xcode. Build the "gtest" target. The universal binary framework will
222 end up in your selected build directory (selected in the Xcode
223 "Preferences..." -> "Building" pane and defaults to xcode/build).
224 Alternatively, at the command line, enter:
228 This will build the "Release" configuration of gtest.framework in your
229 default build location. See the "xcodebuild" man page for more
230 information about building different configurations and building in
233 If you wish to use the Google Test Xcode project with Xcode 4.x and
234 above, you need to either:
236 * update the SDK configuration options in xcode/Config/General.xconfig.
237 Comment options `SDKROOT`, `MACOS_DEPLOYMENT_TARGET`, and `GCC_VERSION`. If
238 you choose this route you lose the ability to target earlier versions
240 * Install an SDK for an earlier version. This doesn't appear to be
241 supported by Apple, but has been reported to work
242 (http://stackoverflow.com/questions/5378518).
244 ### Tweaking Google Test ###
246 Google Test can be used in diverse environments. The default
247 configuration may not work (or may not work well) out of the box in
248 some environments. However, you can easily tweak Google Test by
249 defining control macros on the compiler command line. Generally,
250 these macros are named like `GTEST_XYZ` and you define them to either 1
251 or 0 to enable or disable a certain feature.
253 We list the most frequently used macros below. For a complete list,
254 see file [include/gtest/internal/gtest-port.h](include/gtest/internal/gtest-port.h).
256 ### Choosing a TR1 Tuple Library ###
258 Some Google Test features require the C++ Technical Report 1 (TR1)
259 tuple library, which is not yet available with all compilers. The
260 good news is that Google Test implements a subset of TR1 tuple that's
261 enough for its own need, and will automatically use this when the
262 compiler doesn't provide TR1 tuple.
264 Usually you don't need to care about which tuple library Google Test
265 uses. However, if your project already uses TR1 tuple, you need to
266 tell Google Test to use the same TR1 tuple library the rest of your
267 project uses, or the two tuple implementations will clash. To do
270 -DGTEST_USE_OWN_TR1_TUPLE=0
272 to the compiler flags while compiling Google Test and your tests. If
273 you want to force Google Test to use its own tuple library, just add
275 -DGTEST_USE_OWN_TR1_TUPLE=1
277 to the compiler flags instead.
279 If you don't want Google Test to use tuple at all, add
281 -DGTEST_HAS_TR1_TUPLE=0
283 and all features using tuple will be disabled.
285 ### Multi-threaded Tests ###
287 Google Test is thread-safe where the pthread library is available.
288 After `#include "gtest/gtest.h"`, you can check the `GTEST_IS_THREADSAFE`
289 macro to see whether this is the case (yes if the macro is `#defined` to
290 1, no if it's undefined.).
292 If Google Test doesn't correctly detect whether pthread is available
293 in your environment, you can force it with
295 -DGTEST_HAS_PTHREAD=1
299 -DGTEST_HAS_PTHREAD=0
301 When Google Test uses pthread, you may need to add flags to your
302 compiler and/or linker to select the pthread library, or you'll get
303 link errors. If you use the CMake script or the deprecated Autotools
304 script, this is taken care of for you. If you use your own build
305 script, you'll need to read your compiler and linker's manual to
306 figure out what flags to add.
308 ### As a Shared Library (DLL) ###
310 Google Test is compact, so most users can build and link it as a
311 static library for the simplicity. You can choose to use Google Test
312 as a shared library (known as a DLL on Windows) if you prefer.
314 To compile *gtest* as a shared library, add
316 -DGTEST_CREATE_SHARED_LIBRARY=1
318 to the compiler flags. You'll also need to tell the linker to produce
319 a shared library instead - consult your linker's manual for how to do
322 To compile your *tests* that use the gtest shared library, add
324 -DGTEST_LINKED_AS_SHARED_LIBRARY=1
326 to the compiler flags.
328 Note: while the above steps aren't technically necessary today when
329 using some compilers (e.g. GCC), they may become necessary in the
330 future, if we decide to improve the speed of loading the library (see
331 <http://gcc.gnu.org/wiki/Visibility> for details). Therefore you are
332 recommended to always add the above flags when using Google Test as a
333 shared library. Otherwise a future release of Google Test may break
336 ### Avoiding Macro Name Clashes ###
338 In C++, macros don't obey namespaces. Therefore two libraries that
339 both define a macro of the same name will clash if you `#include` both
340 definitions. In case a Google Test macro clashes with another
341 library, you can force Google Test to rename its macro to avoid the
344 Specifically, if both Google Test and some other code define macro
347 -DGTEST_DONT_DEFINE_FOO=1
349 to the compiler flags to tell Google Test to change the macro's name
350 from `FOO` to `GTEST_FOO`. Currently `FOO` can be `FAIL`, `SUCCEED`,
351 or `TEST`. For example, with `-DGTEST_DONT_DEFINE_TEST=1`, you'll
354 GTEST_TEST(SomeTest, DoesThis) { ... }
358 TEST(SomeTest, DoesThis) { ... }
360 in order to define a test.