1 Google C++ Testing Framework

     2 ============================

     3 

     4 http://code.google.com/p/googletest/

     5 

     6 Overview

     7 --------

     8 

     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.

    15 

    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 

    24 Google Test is designed to have fairly minimal requirements to build

    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!

    33 

    34 ### Linux Requirements ###

    35 

    36 These are the base requirements to build and use Google Test from a source

    37 package (as described below):

    38   * GNU-compatible Make or gmake

    39   * POSIX-standard shell

    40   * POSIX(-2) Regular Expressions (regex.h)

    41   * A C++98-standard-compliant compiler

    42 

    43 ### Windows Requirements ###

    44 

    45   * Microsoft Visual C++ 7.1 or newer

    46 

    47 ### Cygwin Requirements ###

    48 

    49   * Cygwin 1.5.25-14 or newer

    50 

    51 ### Mac OS X Requirements ###

    52 

    53   * Mac OS X 10.4 Tiger or newer

    54   * Developer Tools Installed

    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

    69 

    70 Getting the Source

    71 ------------------

    72 

    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.

    79 

    80 ### Source Package ###

    81 

    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.

    87 

    88   [1] http://code.google.com/p/googletest/downloads/list

    89 

    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:

    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 

    99 ### SVN Checkout ###

   100 

   101 To check out the main branch (also known as the "trunk") of Google

   102 Test, run the following Subversion command:

   103 

   104   svn checkout http://googletest.googlecode.com/svn/trunk/ gtest-svn

   105 

   106 Setting up the Build

   107 --------------------

   108 

   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.

   113 

   114 ### Generic Build Instructions ###

   115 

   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

   119 

   120   ${GTEST_DIR}/src/gtest-all.cc

   121 

   122 with ${GTEST_DIR}/include in the system header search path and ${GTEST_DIR}

   123 in the normal header search path.  Assuming a Linux-like system and gcc,

   124 something like the following will do:

   125 

   126   g++ -isystem ${GTEST_DIR}/include -I${GTEST_DIR} \

   127       -pthread -c ${GTEST_DIR}/src/gtest-all.cc

   128   ar -rv libgtest.a gtest-all.o

   129 

   130 (We need -pthread as Google Test uses threads.)

   131 

   132 Next, you should compile your test source file with

   133 ${GTEST_DIR}/include in the system header search path, and link it

   134 with gtest and any other necessary libraries:

   135 

   136   g++ -isystem ${GTEST_DIR}/include -pthread path/to/your_test.cc libgtest.a \

   137       -o your_test

   138 

   139 As an example, the make/ directory contains a Makefile that you can

   140 use to build Google Test on systems where GNU make is available

   141 (e.g. Linux, Mac OS X, and Cygwin).  It doesn't try to build Google

   142 Test's own tests.  Instead, it just builds the Google Test library and

   143 a sample test.  You can use it as a starting point for your own build

   144 script.

   145 

   146 If the default settings are correct for your environment, the

   147 following commands should succeed:

   148 

   149   cd ${GTEST_DIR}/make

   150   make

   151   ./sample1_unittest

   152 

   153 If you see errors, try to tweak the contents of make/Makefile to make

   154 them go away.  There are instructions in make/Makefile on how to do

   155 it.

   156 

   157 ### Using CMake ###

   158 

   159 Google Test comes with a CMake build script (CMakeLists.txt) that can

   160 be used on a wide range of platforms ("C" stands for cross-platofrm.).

   161 If you don't have CMake installed already, you can download it for

   162 free from http://www.cmake.org/.

   163 

   164 CMake works by generating native makefiles or build projects that can

   165 be used in the compiler environment of your choice.  The typical

   166 workflow starts with:

   167 

   168   mkdir mybuild       # Create a directory to hold the build output.

   169   cd mybuild

   170   cmake ${GTEST_DIR}  # Generate native build scripts.

   171 

   172 If you want to build Google Test's samples, you should replace the

   173 last command with

   174 

   175   cmake -Dgtest_build_samples=ON ${GTEST_DIR}

   176 

   177 If you are on a *nix system, you should now see a Makefile in the

   178 current directory.  Just type 'make' to build gtest.

   179 

   180 If you use Windows and have Vistual Studio installed, a gtest.sln file

   181 and several .vcproj files will be created.  You can then build them

   182 using Visual Studio.

   183 

   184 On Mac OS X with Xcode installed, a .xcodeproj file will be generated.

   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 previous two 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  * update the SDK configuration options in xcode/Config/General.xconfig.

   224    Comment options SDKROOT, MACOS_DEPLOYMENT_TARGET, and GCC_VERSION. If

   225    you choose this route you lose the ability to target earlier versions

   226    of MacOS X.

   227  * Install an SDK for an earlier version. This doesn't appear to be

   228    supported by Apple, but has been reported to work

   229    (http://stackoverflow.com/questions/5378518).

   230 

   231 Tweaking Google Test

   232 --------------------

   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.

   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, or TEST.

   339 For example, with -DGTEST_DONT_DEFINE_TEST=1, you'll need to write

   340 

   341   GTEST_TEST(SomeTest, DoesThis) { ... }

   342 

   343 instead of

   344 

   345   TEST(SomeTest, DoesThis) { ... }

   346 

   347 in order to define a test.

   348 

   349 Upgrating from an Earlier Version

   350 ---------------------------------

   351 

   352 We strive to keep Google Test releases backward compatible.

   353 Sometimes, though, we have to make some breaking changes for the

   354 users' long-term benefits.  This section describes what you'll need to

   355 do if you are upgrading from an earlier version of Google Test.

   356 

   357 ### Upgrading from 1.3.0 or Earlier ###

   358 

   359 You may need to explicitly enable or disable Google Test's own TR1

   360 tuple library.  See the instructions in section "Choosing a TR1 Tuple

   361 Library".

   362 

   363 ### Upgrading from 1.4.0 or Earlier ###

   364 

   365 The Autotools build script (configure + make) is no longer officially

   366 supportted.  You are encouraged to migrate to your own build system or

   367 use CMake.  If you still need to use Autotools, you can find

   368 instructions in the README file from Google Test 1.4.0.

   369 

   370 On platforms where the pthread library is available, Google Test uses

   371 it in order to be thread-safe.  See the "Multi-threaded Tests" section

   372 for what this means to your build script.

   373 

   374 If you use Microsoft Visual C++ 7.1 with exceptions disabled, Google

   375 Test will no longer compile.  This should affect very few people, as a

   376 large portion of STL (including <string>) doesn't compile in this mode

   377 anyway.  We decided to stop supporting it in order to greatly simplify

   378 Google Test's implementation.

   379 

   380 Developing Google Test

   381 ----------------------

   382 

   383 This section discusses how to make your own changes to Google Test.

   384 

   385 ### Testing Google Test Itself ###

   386 

   387 To make sure your changes work as intended and don't break existing

   388 functionality, you'll want to compile and run Google Test's own tests.

   389 For that you can use CMake:

   390 

   391   mkdir mybuild

   392   cd mybuild

   393   cmake -Dgtest_build_tests=ON ${GTEST_DIR}

   394 

   395 Make sure you have Python installed, as some of Google Test's tests

   396 are written in Python.  If the cmake command complains about not being

   397 able to find Python ("Could NOT find PythonInterp (missing:

   398 PYTHON_EXECUTABLE)"), try telling it explicitly where your Python

   399 executable can be found:

   400 

   401   cmake -DPYTHON_EXECUTABLE=path/to/python -Dgtest_build_tests=ON ${GTEST_DIR}

   402 

   403 Next, you can build Google Test and all of its own tests.  On *nix,

   404 this is usually done by 'make'.  To run the tests, do

   405 

   406   make test

   407 

   408 All tests should pass.

   409 

   410 ### Regenerating Source Files ###

   411 

   412 Some of Google Test's source files are generated from templates (not

   413 in the C++ sense) using a script.  A template file is named FOO.pump,

   414 where FOO is the name of the file it will generate.  For example, the

   415 file include/gtest/internal/gtest-type-util.h.pump is used to generate

   416 gtest-type-util.h in the same directory.

   417 

   418 Normally you don't need to worry about regenerating the source files,

   419 unless you need to modify them.  In that case, you should modify the

   420 corresponding .pump files instead and run the pump.py Python script to

   421 regenerate them.  You can find pump.py in the scripts/ directory.

   422 Read the Pump manual [2] for how to use it.

   423 

   424   [2] http://code.google.com/p/googletest/wiki/PumpManual

   425 

   426 ### Contributing a Patch ###

   427 

   428 We welcome patches.  Please read the Google Test developer's guide [3]

   429 for how you can contribute.  In particular, make sure you have signed

   430 the Contributor License Agreement, or we won't be able to accept the

   431 patch.

   432 

   433   [3] http://code.google.com/p/googletest/wiki/GoogleTestDevGuide

   434 

   435 Happy testing!