• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Google C++ Testing Framework
2============================
3http://code.google.com/p/googletest/
4
5Overview
6--------
7Google's framework for writing C++ tests on a variety of platforms (Linux, Mac
8OS X, Windows, Windows CE, Symbian, and etc). Based on the xUnit architecture.
9Supports automatic test discovery, a rich set of assertions, user-defined
10assertions, death tests, fatal and non-fatal failures, various options for
11running the tests, and XML test report generation.
12
13Please see the project page above for more information as well as mailing lists
14for questions, discussions, and development. There is also an IRC channel on
15OFTC (irc.oftc.net) #gtest available. Please join us!
16
17Requirements
18------------
19Google Test is designed to have fairly minimal requirements to build
20and use with your projects, but there are some. Currently, we support
21building Google Test on Linux, Windows, Mac OS X, and Cygwin.  We will
22also make our best effort to support other platforms (e.g. Solaris and
23IBM z/OS).  However, since core members of the Google Test project
24have no access to them, Google Test may have outstanding issues on
25these platforms.  If you notice any problems on your platform, please
26notify googletestframework@googlegroups.com (patches for fixing them
27are even more welcome!).
28
29### Linux Requirements ###
30These are the base requirements to build and use Google Test from a source
31package (as described below):
32  * GNU-compatible Make or "gmake"
33  * POSIX-standard shell
34  * POSIX(-2) Regular Expressions (regex.h)
35  * A C++98 standards compliant compiler
36
37Furthermore, if you are building Google Test from a VCS Checkout (also
38described below), there are further requirements:
39  * Automake version 1.9 or newer
40  * Autoconf version 2.59 or newer
41  * Libtool / Libtoolize
42  * Python version 2.4 or newer
43
44### Windows Requirements ###
45  * Microsoft Visual Studio 7.1 or newer
46
47### Cygwin Requirements ###
48  * Cygwin 1.5.25-14 or newer
49
50### Mac OS X Requirements ###
51  * Mac OS X 10.4 Tiger or newer
52  * Developer Tools Installed
53  * Optional: Xcode 2.5 or later for univeral-binary framework; see note below.
54
55Getting the Source
56------------------
57There are two primary ways of getting Google Test's source code: you can
58download a source release in your preferred archive format, or directly check
59out the source from a Version Control System (VCS, we use Google Code's
60Subversion hosting). The VCS checkout requires a few extra steps and some extra
61software packages on your system, but lets you track development, and make
62patches to contribute much more easily, so we highly encourage it.
63
64### VCS Checkout: ###
65The first step is to select whether you want to check out the main line of
66development on Google Test, or one of the released branches. The former will be
67much more active and have the latest features, but the latter provides much
68more stability and predictability. Choose whichever fits your needs best, and
69proceed with the following Subversion commands:
70
71  svn checkout http://googletest.googlecode.com/svn/trunk/ gtest-svn
72
73or for a release version X.Y.*'s branch:
74
75  svn checkout http://googletest.googlecode.com/svn/branches/release-X.Y/ \
76    gtest-X.Y-svn
77
78Next you will need to prepare the GNU Autotools build system, if you
79are using Linux, Mac OS X, or Cygwin. Enter the target directory of
80the checkout command you used ('gtest-svn' or 'gtest-X.Y-svn' above)
81and proceed with the following command:
82
83  autoreconf -fvi
84
85Once you have completed this step, you are ready to build the library. Note
86that you should only need to complete this step once. The subsequent `make'
87invocations will automatically re-generate the bits of the build system that
88need to be changed.
89
90If your system uses older versions of the autotools, the above command will
91fail. You may need to explicitly specify a version to use. For instance, if you
92have both GNU Automake 1.4 and 1.9 installed and `automake' would invoke the
931.4, use instead:
94
95  AUTOMAKE=automake-1.9 ACLOCAL=aclocal-1.9 autoreconf -fvi
96
97Make sure you're using the same version of automake and aclocal.
98
99### Source Package: ###
100Google Test is also released in source packages which can be downloaded from
101its Google Code download page[1]. Several different archive formats are
102provided, but the only difference is the tools used to manipulate them, and the
103size of the resulting file. Download whichever you are most comfortable with.
104
105  [1] Google Test Downloads: http://code.google.com/p/googletest/downloads/list
106
107Once downloaded expand the archive using whichever tools you prefer for that
108type. This will always result in a new directory with the name "gtest-X.Y.Z"
109which contains all of the source code. Here are some examples in Linux:
110
111  tar -xvzf gtest-X.Y.Z.tar.gz
112  tar -xvjf gtest-X.Y.Z.tar.bz2
113  unzip gtest-X.Y.Z.zip
114
115Building the Source
116-------------------
117### Linux, Mac OS X (without Xcode), and Cygwin ###
118There are two primary options for building the source at this point: build it
119inside the source code tree, or in a separate directory. We recommend building
120in a separate directory as that tends to produce both more consistent results
121and be easier to clean up should anything go wrong, but both patterns are
122supported. The only hard restriction is that while the build directory can be
123a subdirectory of the source directory, the opposite is not possible and will
124result in errors. Once you have selected where you wish to build Google Test,
125create the directory if necessary, and enter it. The following steps apply for
126either approach by simply substituting the shell variable SRCDIR with "." for
127building inside the source directory, and the relative path to the source
128directory otherwise.
129
130  ${SRCDIR}/configure  # Standard GNU configure script, --help for more info
131  make  # Standard makefile following GNU conventions
132  make check  # Builds and runs all tests - all should pass
133
134Other programs will only be able to use Google Test's functionality if you
135install it in a location which they can access, in Linux this is typically
136under '/usr/local'. The following command will install all of the Google Test
137libraries, public headers, and utilities necessary for other programs and
138libraries to leverage it:
139
140  sudo make install  # Not necessary, but allows use by other programs
141
142Should you need to remove Google Test from your system after having installed
143it, run the following command, and it will back out its changes.  However, note
144carefully that you must run this command on the *same* Google Test build that
145you ran the install from, or the results are not predictable.  If you install
146Google Test on your system, and are working from a VCS checkout, make sure you
147run this *before* updating your checkout of the source in order to uninstall
148the same version which you installed.
149
150  sudo make uninstall  # Must be run against the exact same build as "install"
151
152Your project can build against Google Test simply by leveraging the
153'gtest-config' script. This script can be invoked directly out of the 'scripts'
154subdirectory of the build tree, and it will be installed in the binary
155directory specified during the 'configure'. Here are some examples of its use,
156see 'gtest-config --help' for more detailed information.
157
158  gtest-config --min-version=1.0 || echo "Insufficient Google Test version."
159
160  g++ $(gtest-config --cppflags --cxxflags) -o foo.o -c foo.cpp
161  g++ $(gtest-config --ldflags --libs) -o foo foo.o
162
163  # When using a built but not installed Google Test:
164  g++ $(../../my_gtest_build/scripts/gtest-config ...) ...
165
166### Windows ###
167Open the gtest.sln file in the msvc/ folder using Visual Studio, and
168you are ready to build Google Test the same way you build any Visual
169Studio project.
170
171### Mac OS X (universal-binary framework) ###
172Open the gtest.xcodeproj in the xcode/ folder using Xcode. Build the "gtest"
173target. The universal binary framework will end up in your selected build
174directory (selected in the Xcode "Preferences..." -> "Building" pane and
175defaults to xcode/build). Alternatively, at the command line, enter:
176
177  xcodebuild
178
179This will build the "Release" configuration of the gtest.framework, but you can
180select the "Debug" configuration with a command line option. See the
181"xcodebuild" man page for more information.
182
183To test the gtest.framework in Xcode, change the active target to "Check" and
184then build. This target builds all of the tests and then runs them. Don't worry
185if you see some errors. Xcode reports all test failures (even the intentional
186ones) as errors. However, you should see a "Build succeeded" message at the end
187of the build log. To run all of the tests from the command line, enter:
188
189  xcodebuid -target Check
190
191It is also possible to build and execute individual tests within Xcode. Each
192test has its own Xcode "Target" and Xcode "Executable". To build any of the
193tests, change the active target and the active executable to the test of
194interest and then build and run.
195
196NOTE: Several tests use a Python script to run the test executable. These can be
197run from Xcode by creating a "Custom Executable". For example, to run the Python
198script which executes the gtest_color_test, select the Project->New Custom
199Executable... menu item. When prompted, set the "Executable Name" to something
200like "run_gtest_color_test" and set the "Executable Path" to the path of the
201gtest_color_test.py script. Finally, choose "Run" from the Run menu and check
202the Console for the results.
203
204Individual tests can be built from the command line using:
205
206  xcodebuild -target <test_name>
207
208These tests can be executed from the command line by moving to the build
209directory and then (in bash)
210
211  export DYLD_FRAMEWORK_PATH=`pwd`
212  ./<test_name>  # (if it is not a python test, e.g. ./gtest_unittest)
213  # OR
214  ./<test_name>.py  # (if it is a python test, e.g. ./gtest_color_test.py)
215
216To use the gtest.framework for your own tests, first, add the framework to Xcode
217project. Next, create a new executable target and add the framework to the
218"Link Binary With Libraries" build phase. Select "Edit Active Executable" from
219the "Project" menu. In the "Arguments" tab, add
220
221    "DYLD_FRAMEWORK_PATH" : "/real/framework/path"
222
223in the "Variables to be set in the environment:" list, where you replace
224"/real/framework/path" with the actual location of the gtest.framework. Now
225when you run your executable, it will load the framework and your test will
226run as expected.
227
228### Using GNU Make ###
229The make/ directory contains a Makefile that you can use to build
230Google Test on systems where GNU make is available (e.g. Linux, Mac OS
231X, and Cygwin).  It doesn't try to build Google Test's own tests.
232Instead, it just builds the Google Test library and a sample test.
233You can use it as a starting point for your own Makefile.
234
235If the default settings are correct for your environment, the
236following commands should succeed:
237
238  cd ${SRCDIR}/make
239  make
240  ./sample1_unittest
241
242If you see errors, try to tweak the contents of make/Makefile to make
243them go away.  There are instructions in make/Makefile on how to do
244it.
245
246### Using Your Own Build System ###
247If none of the build solutions we provide works for you, or if you
248prefer your own build system, you just need to compile
249src/gtest-all.cc into a library and link your tests with it.  Assuming
250a Linux-like system and gcc, something like the following will do:
251
252  cd ${SRCDIR}
253  g++ -I. -I./include -c src/gtest-all.cc
254  ar -rv libgtest.a gtest-all.o
255  g++ -I. -I./include path/to/your_test.cc libgtest.a -o your_test
256
257Regenerating Source Files
258-------------------------
259Some of Google Test's source files are generated from templates (not
260in the C++ sense) using a script.  A template file is named FOO.pump,
261where FOO is the name of the file it will generate.  For example, the
262file include/gtest/internal/gtest-type-util.h.pump is used to generate
263gtest-type-util.h in the same directory.
264
265Normally you don't need to worry about regenerating the source files,
266unless you need to modify them (e.g. if you are working on a patch for
267Google Test).  In that case, you should modify the corresponding .pump
268files instead and run the 'pump' script (for Pump is Useful for Meta
269Programming) to regenerate them.  We are still working on releasing
270the script and its documentation.  If you need it now, please email
271googletestframework@googlegroups.com such that we know to make it
272happen sooner.
273
274Happy testing!
275