README.md 15.6 KB
Newer Older
shiqian's avatar
shiqian committed
1
2
Google C++ Testing Framework
============================
3

Billy Donahue's avatar
Billy Donahue committed
4
https://github.com/google/googletest
shiqian's avatar
shiqian committed
5
6
7

Overview
--------
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Google's framework for writing C++ tests on a variety of platforms
(Linux, Mac OS X, Windows, Windows CE, Symbian, etc).  Based on the
xUnit architecture.  Supports automatic test discovery, a rich set of
assertions, user-defined assertions, death tests, fatal and non-fatal
failures, various options for running the tests, and XML test report
generation.

Please see the project page above for more information as well as the
mailing list for questions, discussions, and development.  There is
also an IRC channel on OFTC (irc.oftc.net) #gtest available.  Please
join us!

Requirements for End Users
--------------------------

24
Google Test is designed to have fairly minimal requirements to build
25
26
27
28
29
30
and use with your projects, but there are some.  Currently, we support
Linux, Windows, Mac OS X, and Cygwin.  We will also make our best
effort to support other platforms (e.g. Solaris, AIX, and z/OS).
However, since core members of the Google Test project have no access
to these platforms, Google Test may have outstanding issues there.  If
you notice any problems on your platform, please notify
Billy Donahue's avatar
Billy Donahue committed
31
<googletestframework@googlegroups.com>. Patches for fixing them are
32
even more welcome!
shiqian's avatar
shiqian committed
33
34

### Linux Requirements ###
35

shiqian's avatar
shiqian committed
36
37
These are the base requirements to build and use Google Test from a source
package (as described below):
Billy Donahue's avatar
Billy Donahue committed
38

39
  * GNU-compatible Make or gmake
shiqian's avatar
shiqian committed
40
41
  * POSIX-standard shell
  * POSIX(-2) Regular Expressions (regex.h)
42
  * A C++98-standard-compliant compiler
shiqian's avatar
shiqian committed
43

44
### Windows Requirements ###
45
46

  * Microsoft Visual C++ 7.1 or newer
47
48

### Cygwin Requirements ###
49

50
51
52
  * Cygwin 1.5.25-14 or newer

### Mac OS X Requirements ###
53

54
  * Mac OS X 10.4 Tiger or newer
55
  * Developer Tools Installed
56

Billy Donahue's avatar
Billy Donahue committed
57
58
59
Also, you'll need [CMake](http://www.cmake.org/ CMake) 2.6.4 or higher if
you want to build the samples using the provided CMake script, regardless
of the platform.
60
61
62
63
64

Requirements for Contributors
-----------------------------

We welcome patches.  If you plan to contribute a patch, you need to
Billy Donahue's avatar
Billy Donahue committed
65
build Google Test and its own tests from a git checkout (described
66
67
below), which has further requirements:

Billy Donahue's avatar
Billy Donahue committed
68
  * [Python](http://python.org/) version 2.3 or newer (for running some of the tests and
69
    re-generating certain source files from templates)
Billy Donahue's avatar
Billy Donahue committed
70
  * [CMake](http://www.cmake.org/) 2.6.4 or newer
71

shiqian's avatar
shiqian committed
72
73
Getting the Source
------------------
74

Billy Donahue's avatar
Billy Donahue committed
75
76
77
78
Google Test's source is available from its GitHub repository at
<https://github.com/google/googletest>.
The GitHub repository offers stable tagged releases available as .ZIP archives. 
A Git checkout requires a few extra steps and some extra software
79
80
81
82
83
packages on your system, but lets you track the latest development and
make patches much more easily, so we highly encourage it.

### Source Package ###

Billy Donahue's avatar
Billy Donahue committed
84
85
Snapshots of Google Test's master branch can be
[https://github.com/google/googletest/archive/master.zip](downloaded directly).
86

Billy Donahue's avatar
Billy Donahue committed
87
88
Versioned releases are also available by clicking on
[https://github.com/google/googletest/releases](Releases) in the project page.
89

Billy Donahue's avatar
Billy Donahue committed
90
### Git Checkout ###
91

Billy Donahue's avatar
Billy Donahue committed
92
To check out the master branch of Google Test, run the following git command:
shiqian's avatar
shiqian committed
93

Billy Donahue's avatar
Billy Donahue committed
94
    git clone https://github.com/google/googletest.git (via HTTPS)
shiqian's avatar
shiqian committed
95

96
97
Setting up the Build
--------------------
shiqian's avatar
shiqian committed
98

99
100
101
102
To build Google Test and your tests that use it, you need to tell your
build system where to find its headers and source files.  The exact
way to do it depends on which build system you use, and is usually
straightforward.
shiqian's avatar
shiqian committed
103

104
### Generic Build Instructions ###
shiqian's avatar
shiqian committed
105

Billy Donahue's avatar
Billy Donahue committed
106
Suppose you put Google Test in directory `${GTEST_DIR}`.  To build it,
107
108
create a library build target (or a project as called by Visual Studio
and Xcode) to compile
shiqian's avatar
shiqian committed
109

Billy Donahue's avatar
Billy Donahue committed
110
    ${GTEST_DIR}/src/gtest-all.cc
shiqian's avatar
shiqian committed
111

Billy Donahue's avatar
Billy Donahue committed
112
with `${GTEST_DIR}/include` in the system header search path and `${GTEST_DIR}`
113
in the normal header search path.  Assuming a Linux-like system and gcc,
114
something like the following will do:
shiqian's avatar
shiqian committed
115

Billy Donahue's avatar
Billy Donahue committed
116
117
118
    g++ -isystem ${GTEST_DIR}/include -I${GTEST_DIR} \
        -pthread -c ${GTEST_DIR}/src/gtest-all.cc
    ar -rv libgtest.a gtest-all.o
shiqian's avatar
shiqian committed
119

Billy Donahue's avatar
Billy Donahue committed
120
(We need `-pthread` as Google Test uses threads.)
121

122
Next, you should compile your test source file with
Billy Donahue's avatar
Billy Donahue committed
123
`${GTEST_DIR}/include` in the system header search path, and link it
124
with gtest and any other necessary libraries:
shiqian's avatar
shiqian committed
125

Billy Donahue's avatar
Billy Donahue committed
126
127
    g++ -isystem ${GTEST_DIR}/include -pthread path/to/your_test.cc libgtest.a \
        -o your_test
shiqian's avatar
shiqian committed
128

129
130
131
132
133
134
135
136
137
138
As an example, the make/ directory contains a Makefile that you can
use to build Google Test on systems where GNU make is available
(e.g. Linux, Mac OS X, and Cygwin).  It doesn't try to build Google
Test's own tests.  Instead, it just builds the Google Test library and
a sample test.  You can use it as a starting point for your own build
script.

If the default settings are correct for your environment, the
following commands should succeed:

Billy Donahue's avatar
Billy Donahue committed
139
140
141
    cd ${GTEST_DIR}/make
    make
    ./sample1_unittest
142

Billy Donahue's avatar
Billy Donahue committed
143
144
If you see errors, try to tweak the contents of `make/Makefile` to make
them go away.  There are instructions in `make/Makefile` on how to do
145
146
147
148
it.

### Using CMake ###

Billy Donahue's avatar
Billy Donahue committed
149
150
151
152
Google Test comes with a CMake build script (
[CMakeLists.txt](https://github.com/google/googletest/blob/master/CMakeLists.txt)) that can be used on a wide range of platforms ("C" stands for
cross-platform.). If you don't have CMake installed already, you can
download it for free from <http://www.cmake.org/>.
153
154
155
156
157

CMake works by generating native makefiles or build projects that can
be used in the compiler environment of your choice.  The typical
workflow starts with:

Billy Donahue's avatar
Billy Donahue committed
158
159
160
    mkdir mybuild       # Create a directory to hold the build output.
    cd mybuild
    cmake ${GTEST_DIR}  # Generate native build scripts.
161
162
163
164

If you want to build Google Test's samples, you should replace the
last command with

Billy Donahue's avatar
Billy Donahue committed
165
    cmake -Dgtest_build_samples=ON ${GTEST_DIR}
166

Billy Donahue's avatar
Billy Donahue committed
167
If you are on a \*nix system, you should now see a Makefile in the
168
169
current directory.  Just type 'make' to build gtest.

Billy Donahue's avatar
Billy Donahue committed
170
171
If you use Windows and have Visual Studio installed, a `gtest.sln` file
and several `.vcproj` files will be created.  You can then build them
172
173
using Visual Studio.

Billy Donahue's avatar
Billy Donahue committed
174
On Mac OS X with Xcode installed, a `.xcodeproj` file will be generated.
175
176
177
178
179
180
181
182
183
184
185
186
187

### Legacy Build Scripts ###

Before settling on CMake, we have been providing hand-maintained build
projects/scripts for Visual Studio, Xcode, and Autotools.  While we
continue to provide them for convenience, they are not actively
maintained any more.  We highly recommend that you follow the
instructions in the previous two sections to integrate Google Test
with your existing build system.

If you still need to use the legacy build scripts, here's how:

The msvc\ folder contains two solutions with Visual C++ projects.
Billy Donahue's avatar
Billy Donahue committed
188
Open the `gtest.sln` or `gtest-md.sln` file using Visual Studio, and you
189
190
191
192
193
194
195
196
197
are ready to build Google Test the same way you build any Visual
Studio project.  Files that have names ending with -md use DLL
versions of Microsoft runtime libraries (the /MD or the /MDd compiler
option).  Files without that suffix use static versions of the runtime
libraries (the /MT or the /MTd option).  Please note that one must use
the same option to compile both gtest and the test code.  If you use
Visual Studio 2005 or above, we recommend the -md version as /MD is
the default for new projects in these versions of Visual Studio.

Billy Donahue's avatar
Billy Donahue committed
198
On Mac OS X, open the `gtest.xcodeproj` in the `xcode/` folder using
199
200
201
202
203
Xcode.  Build the "gtest" target.  The universal binary framework will
end up in your selected build directory (selected in the Xcode
"Preferences..." -> "Building" pane and defaults to xcode/build).
Alternatively, at the command line, enter:

Billy Donahue's avatar
Billy Donahue committed
204
    xcodebuild
205
206
207
208
209
210

This will build the "Release" configuration of gtest.framework in your
default build location.  See the "xcodebuild" man page for more
information about building different configurations and building in
different locations.

211
212
If you wish to use the Google Test Xcode project with Xcode 4.x and
above, you need to either:
Billy Donahue's avatar
Billy Donahue committed
213

214
 * update the SDK configuration options in xcode/Config/General.xconfig.
Billy Donahue's avatar
Billy Donahue committed
215
   Comment options `SDKROOT`, `MACOS_DEPLOYMENT_TARGET`, and `GCC_VERSION`. If
216
217
218
219
220
221
   you choose this route you lose the ability to target earlier versions
   of MacOS X.
 * Install an SDK for an earlier version. This doesn't appear to be
   supported by Apple, but has been reported to work
   (http://stackoverflow.com/questions/5378518).

222
223
224
225
226
227
228
Tweaking Google Test
--------------------

Google Test can be used in diverse environments.  The default
configuration may not work (or may not work well) out of the box in
some environments.  However, you can easily tweak Google Test by
defining control macros on the compiler command line.  Generally,
Billy Donahue's avatar
Billy Donahue committed
229
these macros are named like `GTEST_XYZ` and you define them to either 1
230
231
232
or 0 to enable or disable a certain feature.

We list the most frequently used macros below.  For a complete list,
Billy Donahue's avatar
Billy Donahue committed
233
see file [include/gtest/internal/gtest-port.h](https://github.com/google/googletest/blob/master/include/gtest/internal/gtest-port.h).
234
235

### Choosing a TR1 Tuple Library ###
shiqian's avatar
shiqian committed
236

237
Some Google Test features require the C++ Technical Report 1 (TR1)
238
239
240
241
tuple library, which is not yet available with all compilers.  The
good news is that Google Test implements a subset of TR1 tuple that's
enough for its own need, and will automatically use this when the
compiler doesn't provide TR1 tuple.
242
243
244
245

Usually you don't need to care about which tuple library Google Test
uses.  However, if your project already uses TR1 tuple, you need to
tell Google Test to use the same TR1 tuple library the rest of your
246
247
project uses, or the two tuple implementations will clash.  To do
that, add
248

Billy Donahue's avatar
Billy Donahue committed
249
    -DGTEST_USE_OWN_TR1_TUPLE=0
250

251
252
253
to the compiler flags while compiling Google Test and your tests.  If
you want to force Google Test to use its own tuple library, just add

Billy Donahue's avatar
Billy Donahue committed
254
    -DGTEST_USE_OWN_TR1_TUPLE=1
255
256

to the compiler flags instead.
257
258
259

If you don't want Google Test to use tuple at all, add

Billy Donahue's avatar
Billy Donahue committed
260
    -DGTEST_HAS_TR1_TUPLE=0
261

262
and all features using tuple will be disabled.
263

264
### Multi-threaded Tests ###
265

266
Google Test is thread-safe where the pthread library is available.
Billy Donahue's avatar
Billy Donahue committed
267
268
After `#include "gtest/gtest.h"`, you can check the `GTEST_IS_THREADSAFE`
macro to see whether this is the case (yes if the macro is `#defined` to
269
1, no if it's undefined.).
270

271
272
If Google Test doesn't correctly detect whether pthread is available
in your environment, you can force it with
273

Billy Donahue's avatar
Billy Donahue committed
274
    -DGTEST_HAS_PTHREAD=1
275

276
or
277

Billy Donahue's avatar
Billy Donahue committed
278
    -DGTEST_HAS_PTHREAD=0
279

280
281
282
283
284
285
When Google Test uses pthread, you may need to add flags to your
compiler and/or linker to select the pthread library, or you'll get
link errors.  If you use the CMake script or the deprecated Autotools
script, this is taken care of for you.  If you use your own build
script, you'll need to read your compiler and linker's manual to
figure out what flags to add.
286

287
### As a Shared Library (DLL) ###
288

289
290
291
Google Test is compact, so most users can build and link it as a
static library for the simplicity.  You can choose to use Google Test
as a shared library (known as a DLL on Windows) if you prefer.
292

293
To compile *gtest* as a shared library, add
294

Billy Donahue's avatar
Billy Donahue committed
295
    -DGTEST_CREATE_SHARED_LIBRARY=1
296

297
298
299
to the compiler flags.  You'll also need to tell the linker to produce
a shared library instead - consult your linker's manual for how to do
it.
300

301
To compile your *tests* that use the gtest shared library, add
302

Billy Donahue's avatar
Billy Donahue committed
303
    -DGTEST_LINKED_AS_SHARED_LIBRARY=1
304

305
to the compiler flags.
306

307
308
309
Note: while the above steps aren't technically necessary today when
using some compilers (e.g. GCC), they may become necessary in the
future, if we decide to improve the speed of loading the library (see
Billy Donahue's avatar
Billy Donahue committed
310
<http://gcc.gnu.org/wiki/Visibility> for details).  Therefore you are
311
312
313
314
recommended to always add the above flags when using Google Test as a
shared library.  Otherwise a future release of Google Test may break
your build script.

315
### Avoiding Macro Name Clashes ###
316

317
318
319
320
321
In C++, macros don't obey namespaces.  Therefore two libraries that
both define a macro of the same name will clash if you #include both
definitions.  In case a Google Test macro clashes with another
library, you can force Google Test to rename its macro to avoid the
conflict.
322

323
324
Specifically, if both Google Test and some other code define macro
FOO, you can add
325

Billy Donahue's avatar
Billy Donahue committed
326
    -DGTEST_DONT_DEFINE_FOO=1
327

328
to the compiler flags to tell Google Test to change the macro's name
Billy Donahue's avatar
Billy Donahue committed
329
330
331
from `FOO` to `GTEST_FOO`.  Currently `FOO` can be `FAIL`, `SUCCEED`,
or `TEST`.  For example, with `-DGTEST_DONT_DEFINE_TEST=1`, you'll
need to write
332

Billy Donahue's avatar
Billy Donahue committed
333
    GTEST_TEST(SomeTest, DoesThis) { ... }
334

335
instead of
336

Billy Donahue's avatar
Billy Donahue committed
337
    TEST(SomeTest, DoesThis) { ... }
338

339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
in order to define a test.

Upgrating from an Earlier Version
---------------------------------

We strive to keep Google Test releases backward compatible.
Sometimes, though, we have to make some breaking changes for the
users' long-term benefits.  This section describes what you'll need to
do if you are upgrading from an earlier version of Google Test.

### Upgrading from 1.3.0 or Earlier ###

You may need to explicitly enable or disable Google Test's own TR1
tuple library.  See the instructions in section "Choosing a TR1 Tuple
Library".

### Upgrading from 1.4.0 or Earlier ###

The Autotools build script (configure + make) is no longer officially
supportted.  You are encouraged to migrate to your own build system or
use CMake.  If you still need to use Autotools, you can find
instructions in the README file from Google Test 1.4.0.

On platforms where the pthread library is available, Google Test uses
it in order to be thread-safe.  See the "Multi-threaded Tests" section
for what this means to your build script.

If you use Microsoft Visual C++ 7.1 with exceptions disabled, Google
Test will no longer compile.  This should affect very few people, as a
large portion of STL (including <string>) doesn't compile in this mode
anyway.  We decided to stop supporting it in order to greatly simplify
Google Test's implementation.

Developing Google Test
----------------------

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

### Testing Google Test Itself ###

To make sure your changes work as intended and don't break existing
functionality, you'll want to compile and run Google Test's own tests.
For that you can use CMake:

Billy Donahue's avatar
Billy Donahue committed
383
384
385
    mkdir mybuild
    cd mybuild
    cmake -Dgtest_build_tests=ON ${GTEST_DIR}
386
387
388

Make sure you have Python installed, as some of Google Test's tests
are written in Python.  If the cmake command complains about not being
Billy Donahue's avatar
Billy Donahue committed
389
390
able to find Python (`Could NOT find PythonInterp (missing:
PYTHON_EXECUTABLE)`), try telling it explicitly where your Python
391
392
executable can be found:

Billy Donahue's avatar
Billy Donahue committed
393
    cmake -DPYTHON_EXECUTABLE=path/to/python -Dgtest_build_tests=ON ${GTEST_DIR}
394

Billy Donahue's avatar
Billy Donahue committed
395
Next, you can build Google Test and all of its own tests.  On \*nix,
396
397
this is usually done by 'make'.  To run the tests, do

Billy Donahue's avatar
Billy Donahue committed
398
    make test
399
400
401
402

All tests should pass.

### Regenerating Source Files ###
403

404
405
406
407
408
409
410
Some of Google Test's source files are generated from templates (not
in the C++ sense) using a script.  A template file is named FOO.pump,
where FOO is the name of the file it will generate.  For example, the
file include/gtest/internal/gtest-type-util.h.pump is used to generate
gtest-type-util.h in the same directory.

Normally you don't need to worry about regenerating the source files,
411
412
413
unless you need to modify them.  In that case, you should modify the
corresponding .pump files instead and run the pump.py Python script to
regenerate them.  You can find pump.py in the scripts/ directory.
Billy Donahue's avatar
Billy Donahue committed
414
415
Read the [Pump manual](http://code.google.com/p/googletest/wiki/PumpManual)
for how to use it.
416
417
418

### Contributing a Patch ###

Billy Donahue's avatar
Billy Donahue committed
419
420
421
We welcome patches.  Please read the
[Google Test developer's guide](
    http://code.google.com/p/googletest/wiki/GoogleTestDevGuide)
422
423
424
425
for how you can contribute.  In particular, make sure you have signed
the Contributor License Agreement, or we won't be able to accept the
patch.

426

shiqian's avatar
shiqian committed
427
Happy testing!