1*** NOTE: The files in the open-vcdiff/src/gtest directory are only a subset of
2*** the full Google Test package. If you want to use Google Test with a
3*** project other than open-vcdiff, please do not use this bundled copy.
4*** Instead, please download the latest version of Google Test from:
5*** http://code.google.com/p/googletest/
6
7Google C++ Testing Framework
8============================
9http://code.google.com/p/googletest/
10
11Overview
12--------
13Google's framework for writing C++ tests on a variety of platforms (Linux, Mac
14OS X, Windows, Windows CE, and Symbian). Based on the xUnit architecture.
15Supports automatic test discovery, a rich set of assertions, user-defined
16assertions, death tests, fatal and non-fatal failures, various options for
17running the tests, and XML test report generation.
18
19Please see the project page above for more information as well as mailing lists
20for questions, discussions, and development. There is also an IRC channel on
21OFTC (irc.oftc.net) #gtest available. Please join us!
22
23Requirements
24------------
25Google Test is designed to have fairly minimal requirements to build and use
26with your projects, but there are some. Currently, the only Operating System
27(OS) on which Google Test is known to build properly is Linux, but we are
28actively working on Windows and Mac support as well. The source code itself is
29already portable across many other platforms, but we are still developing
30robust build systems for each.
31
32### Linux Requirements ###
33These are the base requirements to build and use Google Test from a source
34package (as described below):
35 * GNU-compatible Make or "gmake"
36 * POSIX-standard shell
37 * POSIX(-2) Regular Expressions (regex.h)
38 * A C++98 standards compliant compiler
39
40Furthermore, if you are building Google Test from a VCS Checkout (also
41described below), there are further requirements:
42 * Automake version 1.9 or newer
43 * Autoconf version 2.59 or newer
44 * Libtool / Libtoolize
45 * Python version 2.4 or newer
46
47### Windows Requirements ###
48 * Microsoft Visual Studio 7.1 or newer
49
50### Cygwin Requirements ###
51 * Cygwin 1.5.25-14 or newer
52
53### Mac OS X Requirements ###
54 * Mac OS X 10.4 Tiger or newer
55
56Getting the Source
57------------------
58There are two primary ways of getting Google Test's source code: you can
59download a source release in your preferred archive format, or directly check
60out the source from a Version Control System (VCS, we use Google Code's
61Subversion hosting). The VCS checkout requires a few extra steps and some extra
62software packages on your system, but lets you track development, and make
63patches to contribute much more easily, so we highly encourage it.
64
65### VCS Checkout: ###
66The first step is to select whether you want to check out the main line of
67development on Google Test, or one of the released branches. The former will be
68much more active and have the latest features, but the latter provides much
69more stability and predictability. Choose whichever fits your needs best, and
70proceed with the following Subversion commands:
71
72 $ svn checkout http://googletest.googlecode.com/svn/trunk/ gtest-svn
73
74or for a release version X.Y.*'s branch:
75
76 $ svn checkout http://googletest.googlecode.com/svn/branches/release-X.Y/ 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 commands:
82
83 $ aclocal-1.9 # Where "1.9" must match the following automake command.
84 $ libtoolize -c # Use "glibtoolize -c" instead on Mac OS X.
85 $ autoheader
86 $ automake-1.9 -ac # See Automake version requirements above.
87 $ autoconf
88
89While this is a bit complicated, it will most often be automatically re-run by
90your "make" invocations, so in practice you shouldn't need to worry too much.
91Once you have completed these steps, you are ready to build the library.
92
93### Source Package: ###
94Google Test is also released in source packages which can be downloaded from
95its Google Code download page[1]. Several different archive formats are
96provided, but the only difference is the tools used to manipulate them, and the
97size of the resulting file. Download whichever you are most comfortable with.
98
99 [1] Google Test Downloads: http://code.google.com/p/googletest/downloads/list
100
101Once downloaded expand the archive using whichever tools you prefer for that
102type. This will always result in a new directory with the name "gtest-X.Y.Z"
103which contains all of the source code. Here are some examples in Linux:
104
105 $ tar -xvzf gtest-X.Y.Z.tar.gz
106 $ tar -xvjf gtest-X.Y.Z.tar.bz2
107 $ unzip gtest-X.Y.Z.zip
108
109Building the Source
110-------------------
111
112### Linux, Mac OS X, and Cygwin ###
113There are two primary options for building the source at this point: build it
114inside the source code tree, or in a separate directory. We recommend building
115in a separate directory as that tends to produce both more consistent results
116and be easier to clean up should anything go wrong, but both patterns are
117supported. The only hard restriction is that while the build directory can be
118a subdirectory of the source directory, the opposite is not possible and will
119result in errors. Once you have selected where you wish to build Google Test,
120create the directory if necessary, and enter it. The following steps apply for
121either approach by simply substituting the shell variable SRCDIR with "." for
122building inside the source directory, and the relative path to the source
123directory otherwise.
124
125 $ ${SRCDIR}/configure # Standard GNU configure script, --help for more info
126 $ make # Standard makefile following GNU conventions
127 $ make check # Builds and runs all tests - all should pass
128
129Other programs will only be able to use Google Test's functionality if you
130install it in a location which they can access, in Linux this is typically
131under '/usr/local'. The following command will install all of the Google Test
132libraries, public headers, and utilities necessary for other programs and
133libraries to leverage it:
134
135 $ sudo make install # Not necessary, but allows use by other programs
136
137TODO(chandlerc@google.com): This section needs to be expanded when the
138'gtest-config' script is finished and Autoconf macro's are provided (or not
139provided) in order to properly reflect the process for other programs to
140locate, include, and link against Google Test.
141
142Finally, should you need to remove Google Test from your system after having
143installed it, run the following command, and it will back out its changes.
144However, note carefully that you must run this command on the *same* Google
145Test build that you ran the install from, or the results are not predictable.
146If you install Google Test on your system, and are working from a VCS checkout,
147make sure you run this *before* updating your checkout of the source in order
148to uninstall the same version which you installed.
149
150 $ sudo make uninstall # Must be run against the exact same build as "install"
151
152### Windows ###
153Open the gtest.sln file in the msvc/ folder using Visual Studio, and
154you are ready to build Google Test the same way you build any Visual
155Studio project.
156
157Happy testing!
158