@@ -59,7 +59,13 @@ cross-platform.). If you don't have CMake installed already, you can
5959download it for free from < http://www.cmake.org/ > .
6060
6161CMake works by generating native makefiles or build projects that can
62- be used in the compiler environment of your choice. The typical
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
6369workflow starts with:
6470
6571 mkdir mybuild # Create a directory to hold the build output.
@@ -80,13 +86,110 @@ using Visual Studio.
8086
8187On Mac OS X with Xcode installed, a ` .xcodeproj ` file will be generated.
8288
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+
83186### Legacy Build Scripts ###
84187
85188Before settling on CMake, we have been providing hand-maintained build
86189projects/scripts for Visual Studio, Xcode, and Autotools. While we
87190continue to provide them for convenience, they are not actively
88191maintained any more. We highly recommend that you follow the
89- instructions in the previous two sections to integrate Google Test
192+ instructions in the above sections to integrate Google Test
90193with your existing build system.
91194
92195If you still need to use the legacy build scripts, here's how:
0 commit comments