Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 1 | Google C++ Testing Framework |
| 2 | ============================ |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 3 | |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 4 | http://code.google.com/p/googletest/ |
| 5 | |
| 6 | Overview |
| 7 | -------- |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 8 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 9 | Google's framework for writing C++ tests on a variety of platforms |
| 10 | (Linux, Mac OS X, Windows, Windows CE, Symbian, etc). Based on the |
| 11 | xUnit architecture. Supports automatic test discovery, a rich set of |
| 12 | assertions, user-defined assertions, death tests, fatal and non-fatal |
| 13 | failures, various options for running the tests, and XML test report |
| 14 | generation. |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 15 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 16 | Please see the project page above for more information as well as the |
| 17 | mailing list for questions, discussions, and development. There is |
| 18 | also an IRC channel on OFTC (irc.oftc.net) #gtest available. Please |
| 19 | join us! |
| 20 | |
| 21 | Requirements for End Users |
| 22 | -------------------------- |
| 23 | |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 24 | Google Test is designed to have fairly minimal requirements to build |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 25 | and use with your projects, but there are some. Currently, we support |
| 26 | Linux, Windows, Mac OS X, and Cygwin. We will also make our best |
| 27 | effort to support other platforms (e.g. Solaris, AIX, and z/OS). |
| 28 | However, since core members of the Google Test project have no access |
| 29 | to these platforms, Google Test may have outstanding issues there. If |
| 30 | you notice any problems on your platform, please notify |
| 31 | googletestframework@googlegroups.com. Patches for fixing them are |
| 32 | even more welcome! |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 33 | |
| 34 | ### Linux Requirements ### |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 35 | |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 36 | These are the base requirements to build and use Google Test from a source |
| 37 | package (as described below): |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 38 | * GNU-compatible Make or gmake |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 39 | * POSIX-standard shell |
| 40 | * POSIX(-2) Regular Expressions (regex.h) |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 41 | * A C++98-standard-compliant compiler |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 42 | |
| 43 | ### Windows Requirements ### |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 44 | |
| 45 | * Microsoft Visual C++ 7.1 or newer |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 46 | |
| 47 | ### Cygwin Requirements ### |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 48 | |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 49 | * Cygwin 1.5.25-14 or newer |
| 50 | |
| 51 | ### Mac OS X Requirements ### |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 52 | |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 53 | * Mac OS X 10.4 Tiger or newer |
| 54 | * Developer Tools Installed |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 55 | |
| 56 | Also, you'll need CMake 2.6.4 or higher if you want to build the |
| 57 | samples using the provided CMake script, regardless of the platform. |
| 58 | |
| 59 | Requirements for Contributors |
| 60 | ----------------------------- |
| 61 | |
| 62 | We welcome patches. If you plan to contribute a patch, you need to |
| 63 | build Google Test and its own tests from an SVN checkout (described |
| 64 | below), which has further requirements: |
| 65 | |
| 66 | * Python version 2.3 or newer (for running some of the tests and |
| 67 | re-generating certain source files from templates) |
| 68 | * CMake 2.6.4 or newer |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 69 | |
| 70 | Getting the Source |
| 71 | ------------------ |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 72 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 73 | There are two primary ways of getting Google Test's source code: you |
| 74 | can download a stable source release in your preferred archive format, |
| 75 | or directly check out the source from our Subversion (SVN) repositary. |
| 76 | The SVN checkout requires a few extra steps and some extra software |
| 77 | packages on your system, but lets you track the latest development and |
| 78 | make patches much more easily, so we highly encourage it. |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 79 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 80 | ### Source Package ### |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 81 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 82 | Google Test is released in versioned source packages which can be |
| 83 | downloaded from the download page [1]. Several different archive |
| 84 | formats are provided, but the only difference is the tools used to |
| 85 | manipulate them, and the size of the resulting file. Download |
| 86 | whichever you are most comfortable with. |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 87 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 88 | [1] http://code.google.com/p/googletest/downloads/list |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 89 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 90 | Once the package is downloaded, expand it using whichever tools you |
| 91 | prefer for that type. This will result in a new directory with the |
| 92 | name "gtest-X.Y.Z" which contains all of the source code. Here are |
| 93 | some examples on Linux: |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 94 | |
| 95 | tar -xvzf gtest-X.Y.Z.tar.gz |
| 96 | tar -xvjf gtest-X.Y.Z.tar.bz2 |
| 97 | unzip gtest-X.Y.Z.zip |
| 98 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 99 | ### SVN Checkout ### |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 100 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 101 | To check out the main branch (also known as the "trunk") of Google |
| 102 | Test, run the following Subversion command: |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 103 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 104 | svn checkout http://googletest.googlecode.com/svn/trunk/ gtest-svn |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 105 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 106 | Setting up the Build |
| 107 | -------------------- |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 108 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 109 | To build Google Test and your tests that use it, you need to tell your |
| 110 | build system where to find its headers and source files. The exact |
| 111 | way to do it depends on which build system you use, and is usually |
| 112 | straightforward. |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 113 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 114 | ### Generic Build Instructions ### |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 115 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 116 | Suppose you put Google Test in directory ${GTEST_DIR}. To build it, |
| 117 | create a library build target (or a project as called by Visual Studio |
| 118 | and Xcode) to compile |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 119 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 120 | ${GTEST_DIR}/src/gtest-all.cc |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 121 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 122 | with |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 123 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 124 | ${GTEST_DIR}/include and ${GTEST_DIR} |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 125 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 126 | in the header search path. Assuming a Linux-like system and gcc, |
| 127 | something like the following will do: |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 128 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 129 | g++ -I${GTEST_DIR}/include -I${GTEST_DIR} -c ${GTEST_DIR}/src/gtest-all.cc |
| 130 | ar -rv libgtest.a gtest-all.o |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 131 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 132 | Next, you should compile your test source file with |
| 133 | ${GTEST_DIR}/include in the header search path, and link it with gtest |
| 134 | and any other necessary libraries: |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 135 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 136 | g++ -I${GTEST_DIR}/include path/to/your_test.cc libgtest.a -o your_test |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 137 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 138 | As an example, the make/ directory contains a Makefile that you can |
| 139 | use to build Google Test on systems where GNU make is available |
| 140 | (e.g. Linux, Mac OS X, and Cygwin). It doesn't try to build Google |
| 141 | Test's own tests. Instead, it just builds the Google Test library and |
| 142 | a sample test. You can use it as a starting point for your own build |
| 143 | script. |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 144 | |
| 145 | If the default settings are correct for your environment, the |
| 146 | following commands should succeed: |
| 147 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 148 | cd ${GTEST_DIR}/make |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 149 | make |
| 150 | ./sample1_unittest |
| 151 | |
| 152 | If you see errors, try to tweak the contents of make/Makefile to make |
| 153 | them go away. There are instructions in make/Makefile on how to do |
| 154 | it. |
| 155 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 156 | ### Using CMake ### |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 157 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 158 | Google Test comes with a CMake build script (CMakeLists.txt) that can |
| 159 | be used on a wide range of platforms ("C" stands for cross-platofrm.). |
| 160 | If you don't have CMake installed already, you can download it for |
| 161 | free from http://www.cmake.org/. |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 162 | |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 163 | CMake works by generating native makefiles or build projects that can |
| 164 | be used in the compiler environment of your choice. The typical |
| 165 | workflow starts with: |
| 166 | |
| 167 | mkdir mybuild # Create a directory to hold the build output. |
| 168 | cd mybuild |
| 169 | cmake ${GTEST_DIR} # Generate native build scripts. |
| 170 | |
| 171 | If you want to build Google Test's samples, you should replace the |
| 172 | last command with |
| 173 | |
| 174 | cmake -Dgtest_build_samples=ON ${GTEST_DIR} |
| 175 | |
| 176 | If you are on a *nix system, you should now see a Makefile in the |
| 177 | current directory. Just type 'make' to build gtest. |
| 178 | |
| 179 | If you use Windows and have Vistual Studio installed, a gtest.sln file |
| 180 | and several .vcproj files will be created. You can then build them |
| 181 | using Visual Studio. |
| 182 | |
| 183 | On Mac OS X with Xcode installed, a .xcodeproj file will be generated. |
| 184 | |
| 185 | ### Legacy Build Scripts ### |
| 186 | |
| 187 | Before settling on CMake, we have been providing hand-maintained build |
| 188 | projects/scripts for Visual Studio, Xcode, and Autotools. While we |
| 189 | continue to provide them for convenience, they are not actively |
| 190 | maintained any more. We highly recommend that you follow the |
| 191 | instructions in the previous two sections to integrate Google Test |
| 192 | with your existing build system. |
| 193 | |
| 194 | If you still need to use the legacy build scripts, here's how: |
| 195 | |
| 196 | The msvc\ folder contains two solutions with Visual C++ projects. |
| 197 | Open the gtest.sln or gtest-md.sln file using Visual Studio, and you |
| 198 | are ready to build Google Test the same way you build any Visual |
| 199 | Studio project. Files that have names ending with -md use DLL |
| 200 | versions of Microsoft runtime libraries (the /MD or the /MDd compiler |
| 201 | option). Files without that suffix use static versions of the runtime |
| 202 | libraries (the /MT or the /MTd option). Please note that one must use |
| 203 | the same option to compile both gtest and the test code. If you use |
| 204 | Visual Studio 2005 or above, we recommend the -md version as /MD is |
| 205 | the default for new projects in these versions of Visual Studio. |
| 206 | |
| 207 | On Mac OS X, open the gtest.xcodeproj in the xcode/ folder using |
| 208 | Xcode. Build the "gtest" target. The universal binary framework will |
| 209 | end up in your selected build directory (selected in the Xcode |
| 210 | "Preferences..." -> "Building" pane and defaults to xcode/build). |
| 211 | Alternatively, at the command line, enter: |
| 212 | |
| 213 | xcodebuild |
| 214 | |
| 215 | This will build the "Release" configuration of gtest.framework in your |
| 216 | default build location. See the "xcodebuild" man page for more |
| 217 | information about building different configurations and building in |
| 218 | different locations. |
| 219 | |
| 220 | Tweaking Google Test |
| 221 | -------------------- |
| 222 | |
| 223 | Google Test can be used in diverse environments. The default |
| 224 | configuration may not work (or may not work well) out of the box in |
| 225 | some environments. However, you can easily tweak Google Test by |
| 226 | defining control macros on the compiler command line. Generally, |
| 227 | these macros are named like GTEST_XYZ and you define them to either 1 |
| 228 | or 0 to enable or disable a certain feature. |
| 229 | |
| 230 | We list the most frequently used macros below. For a complete list, |
| 231 | see file include/gtest/internal/gtest-port.h. |
| 232 | |
| 233 | ### Choosing a TR1 Tuple Library ### |
| 234 | |
| 235 | Some Google Test features require the C++ Technical Report 1 (TR1) |
| 236 | tuple library, which is not yet available with all compilers. The |
| 237 | good news is that Google Test implements a subset of TR1 tuple that's |
| 238 | enough for its own need, and will automatically use this when the |
| 239 | compiler doesn't provide TR1 tuple. |
| 240 | |
| 241 | Usually you don't need to care about which tuple library Google Test |
| 242 | uses. However, if your project already uses TR1 tuple, you need to |
| 243 | tell Google Test to use the same TR1 tuple library the rest of your |
| 244 | project uses, or the two tuple implementations will clash. To do |
| 245 | that, add |
| 246 | |
| 247 | -DGTEST_USE_OWN_TR1_TUPLE=0 |
| 248 | |
| 249 | to the compiler flags while compiling Google Test and your tests. If |
| 250 | you want to force Google Test to use its own tuple library, just add |
| 251 | |
| 252 | -DGTEST_USE_OWN_TR1_TUPLE=1 |
| 253 | |
| 254 | to the compiler flags instead. |
| 255 | |
| 256 | If you don't want Google Test to use tuple at all, add |
| 257 | |
| 258 | -DGTEST_HAS_TR1_TUPLE=0 |
| 259 | |
| 260 | and all features using tuple will be disabled. |
| 261 | |
| 262 | ### Multi-threaded Tests ### |
| 263 | |
| 264 | Google Test is thread-safe where the pthread library is available. |
| 265 | After #include "gtest/gtest.h", you can check the GTEST_IS_THREADSAFE |
| 266 | macro to see whether this is the case (yes if the macro is #defined to |
| 267 | 1, no if it's undefined.). |
| 268 | |
| 269 | If Google Test doesn't correctly detect whether pthread is available |
| 270 | in your environment, you can force it with |
| 271 | |
| 272 | -DGTEST_HAS_PTHREAD=1 |
| 273 | |
| 274 | or |
| 275 | |
| 276 | -DGTEST_HAS_PTHREAD=0 |
| 277 | |
| 278 | When Google Test uses pthread, you may need to add flags to your |
| 279 | compiler and/or linker to select the pthread library, or you'll get |
| 280 | link errors. If you use the CMake script or the deprecated Autotools |
| 281 | script, this is taken care of for you. If you use your own build |
| 282 | script, you'll need to read your compiler and linker's manual to |
| 283 | figure out what flags to add. |
| 284 | |
| 285 | ### As a Shared Library (DLL) ### |
| 286 | |
| 287 | Google Test is compact, so most users can build and link it as a |
| 288 | static library for the simplicity. You can choose to use Google Test |
| 289 | as a shared library (known as a DLL on Windows) if you prefer. |
| 290 | |
| 291 | To compile *gtest* as a shared library, add |
| 292 | |
| 293 | -DGTEST_CREATE_SHARED_LIBRARY=1 |
| 294 | |
| 295 | to the compiler flags. You'll also need to tell the linker to produce |
| 296 | a shared library instead - consult your linker's manual for how to do |
| 297 | it. |
| 298 | |
| 299 | To compile your *tests* that use the gtest shared library, add |
| 300 | |
| 301 | -DGTEST_LINKED_AS_SHARED_LIBRARY=1 |
| 302 | |
| 303 | to the compiler flags. |
| 304 | |
| 305 | Note: while the above steps aren't technically necessary today when |
| 306 | using some compilers (e.g. GCC), they may become necessary in the |
| 307 | future, if we decide to improve the speed of loading the library (see |
| 308 | http://gcc.gnu.org/wiki/Visibility for details). Therefore you are |
| 309 | recommended to always add the above flags when using Google Test as a |
| 310 | shared library. Otherwise a future release of Google Test may break |
| 311 | your build script. |
| 312 | |
| 313 | ### Avoiding Macro Name Clashes ### |
| 314 | |
| 315 | In C++, macros don't obey namespaces. Therefore two libraries that |
| 316 | both define a macro of the same name will clash if you #include both |
| 317 | definitions. In case a Google Test macro clashes with another |
| 318 | library, you can force Google Test to rename its macro to avoid the |
| 319 | conflict. |
| 320 | |
| 321 | Specifically, if both Google Test and some other code define macro |
| 322 | FOO, you can add |
| 323 | |
| 324 | -DGTEST_DONT_DEFINE_FOO=1 |
| 325 | |
| 326 | to the compiler flags to tell Google Test to change the macro's name |
| 327 | from FOO to GTEST_FOO. Currently FOO can be FAIL, SUCCEED, or TEST. |
| 328 | For example, with -DGTEST_DONT_DEFINE_TEST=1, you'll need to write |
| 329 | |
| 330 | GTEST_TEST(SomeTest, DoesThis) { ... } |
| 331 | |
| 332 | instead of |
| 333 | |
| 334 | TEST(SomeTest, DoesThis) { ... } |
| 335 | |
| 336 | in order to define a test. |
| 337 | |
| 338 | Upgrating from an Earlier Version |
| 339 | --------------------------------- |
| 340 | |
| 341 | We strive to keep Google Test releases backward compatible. |
| 342 | Sometimes, though, we have to make some breaking changes for the |
| 343 | users' long-term benefits. This section describes what you'll need to |
| 344 | do if you are upgrading from an earlier version of Google Test. |
| 345 | |
| 346 | ### Upgrading from 1.3.0 or Earlier ### |
| 347 | |
| 348 | You may need to explicitly enable or disable Google Test's own TR1 |
| 349 | tuple library. See the instructions in section "Choosing a TR1 Tuple |
| 350 | Library". |
| 351 | |
| 352 | ### Upgrading from 1.4.0 or Earlier ### |
| 353 | |
| 354 | The Autotools build script (configure + make) is no longer officially |
| 355 | supportted. You are encouraged to migrate to your own build system or |
| 356 | use CMake. If you still need to use Autotools, you can find |
| 357 | instructions in the README file from Google Test 1.4.0. |
| 358 | |
| 359 | On platforms where the pthread library is available, Google Test uses |
| 360 | it in order to be thread-safe. See the "Multi-threaded Tests" section |
| 361 | for what this means to your build script. |
| 362 | |
| 363 | If you use Microsoft Visual C++ 7.1 with exceptions disabled, Google |
| 364 | Test will no longer compile. This should affect very few people, as a |
| 365 | large portion of STL (including <string>) doesn't compile in this mode |
| 366 | anyway. We decided to stop supporting it in order to greatly simplify |
| 367 | Google Test's implementation. |
| 368 | |
| 369 | Developing Google Test |
| 370 | ---------------------- |
| 371 | |
| 372 | This section discusses how to make your own changes to Google Test. |
| 373 | |
| 374 | ### Testing Google Test Itself ### |
| 375 | |
| 376 | To make sure your changes work as intended and don't break existing |
| 377 | functionality, you'll want to compile and run Google Test's own tests. |
| 378 | For that you can use CMake: |
| 379 | |
| 380 | mkdir mybuild |
| 381 | cd mybuild |
| 382 | cmake -Dgtest_build_tests=ON ${GTEST_DIR} |
| 383 | |
| 384 | Make sure you have Python installed, as some of Google Test's tests |
| 385 | are written in Python. If the cmake command complains about not being |
| 386 | able to find Python ("Could NOT find PythonInterp (missing: |
| 387 | PYTHON_EXECUTABLE)"), try telling it explicitly where your Python |
| 388 | executable can be found: |
| 389 | |
| 390 | cmake -DPYTHON_EXECUTABLE=path/to/python -Dgtest_build_tests=ON ${GTEST_DIR} |
| 391 | |
| 392 | Next, you can build Google Test and all of its own tests. On *nix, |
| 393 | this is usually done by 'make'. To run the tests, do |
| 394 | |
| 395 | make test |
| 396 | |
| 397 | All tests should pass. |
| 398 | |
| 399 | ### Regenerating Source Files ### |
| 400 | |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 401 | Some of Google Test's source files are generated from templates (not |
| 402 | in the C++ sense) using a script. A template file is named FOO.pump, |
| 403 | where FOO is the name of the file it will generate. For example, the |
| 404 | file include/gtest/internal/gtest-type-util.h.pump is used to generate |
| 405 | gtest-type-util.h in the same directory. |
| 406 | |
| 407 | Normally you don't need to worry about regenerating the source files, |
Brett Chabot | 41d0579 | 2011-11-30 12:44:19 -0800 | [diff] [blame] | 408 | unless you need to modify them. In that case, you should modify the |
| 409 | corresponding .pump files instead and run the pump.py Python script to |
| 410 | regenerate them. You can find pump.py in the scripts/ directory. |
| 411 | Read the Pump manual [2] for how to use it. |
| 412 | |
| 413 | [2] http://code.google.com/p/googletest/wiki/PumpManual |
| 414 | |
| 415 | ### Contributing a Patch ### |
| 416 | |
| 417 | We welcome patches. Please read the Google Test developer's guide [3] |
| 418 | for how you can contribute. In particular, make sure you have signed |
| 419 | the Contributor License Agreement, or we won't be able to accept the |
| 420 | patch. |
| 421 | |
| 422 | [3] http://code.google.com/p/googletest/wiki/GoogleTestDevGuide |
Nicolas Catania | 1be2c9d | 2009-05-28 19:30:30 -0700 | [diff] [blame] | 423 | |
| 424 | Happy testing! |