← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/mozc/oneiric

« back to all changes in this revision

Viewing changes to protobuf/files/gtest/README

  • Committer: Bazaar Package Importer
  • Author(s): Nobuhiro Iwamatsu
  • Date: 2010-07-14 03:26:47 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20100714032647-13qjisj6m8cm8jdx
Tags: 0.12.410.102-1
http://bugs.debian.org/588971
http://bugs.debian.org/588972
* New upstream release (Closes: #588971).
  - Add mozc-server, mozc-utils-gui and scim-mozc packages.
* Update debian/rules.
  Add --gypdir option to build_mozc.py.
* Update debian/control.
  - Bumped standards-version to 3.9.0.
  - Update description.
* Add mozc icon (Closes: #588972).
* Add patch which revises issue 18.
  ibus_mozc_issue18.patch
* kFreeBSD build support.
  support_kfreebsd.patch

Show diffs side-by-side

added added

removed removed

Lines of Context:
protobuf/files/gtest/README
1
 
Google C++ Testing Framework
2
 
============================
3
 
http://code.google.com/p/googletest/
4
 
 
5
 
Overview
6
 
--------
7
 
Google's framework for writing C++ tests on a variety of platforms (Linux, Mac
8
 
OS X, Windows, Windows CE, Symbian, and etc). Based on the xUnit architecture.
9
 
Supports automatic test discovery, a rich set of assertions, user-defined
10
 
assertions, death tests, fatal and non-fatal failures, various options for
11
 
running the tests, and XML test report generation.
12
 
 
13
 
Please see the project page above for more information as well as mailing lists
14
 
for questions, discussions, and development. There is also an IRC channel on
15
 
OFTC (irc.oftc.net) #gtest available. Please join us!
16
 
 
17
 
Requirements
18
 
------------
19
 
Google Test is designed to have fairly minimal requirements to build
20
 
and use with your projects, but there are some. Currently, we support
21
 
building Google Test on Linux, Windows, Mac OS X, and Cygwin.  We will
22
 
also make our best effort to support other platforms (e.g. Solaris and
23
 
IBM z/OS).  However, since core members of the Google Test project
24
 
have no access to them, Google Test may have outstanding issues on
25
 
these platforms.  If you notice any problems on your platform, please
26
 
notify googletestframework@googlegroups.com (patches for fixing them
27
 
are even more welcome!).
28
 
 
29
 
### Linux Requirements ###
30
 
These are the base requirements to build and use Google Test from a source
31
 
package (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
 
 
37
 
Furthermore, if you are building Google Test from a VCS Checkout (also
38
 
described 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
 
 
55
 
Getting the Source
56
 
------------------
57
 
There are two primary ways of getting Google Test's source code: you can
58
 
download a source release in your preferred archive format, or directly check
59
 
out the source from a Version Control System (VCS, we use Google Code's
60
 
Subversion hosting). The VCS checkout requires a few extra steps and some extra
61
 
software packages on your system, but lets you track development, and make
62
 
patches to contribute much more easily, so we highly encourage it.
63
 
 
64
 
### VCS Checkout: ###
65
 
The first step is to select whether you want to check out the main line of
66
 
development on Google Test, or one of the released branches. The former will be
67
 
much more active and have the latest features, but the latter provides much
68
 
more stability and predictability. Choose whichever fits your needs best, and
69
 
proceed with the following Subversion commands:
70
 
 
71
 
  svn checkout http://googletest.googlecode.com/svn/trunk/ gtest-svn
72
 
 
73
 
or 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
 
 
78
 
Next you will need to prepare the GNU Autotools build system, if you
79
 
are using Linux, Mac OS X, or Cygwin. Enter the target directory of
80
 
the checkout command you used ('gtest-svn' or 'gtest-X.Y-svn' above)
81
 
and proceed with the following command:
82
 
 
83
 
  autoreconf -fvi
84
 
 
85
 
Once you have completed this step, you are ready to build the library. Note
86
 
that you should only need to complete this step once. The subsequent `make'
87
 
invocations will automatically re-generate the bits of the build system that
88
 
need to be changed.
89
 
 
90
 
If your system uses older versions of the autotools, the above command will
91
 
fail. You may need to explicitly specify a version to use. For instance, if you
92
 
have both GNU Automake 1.4 and 1.9 installed and `automake' would invoke the
93
 
1.4, use instead:
94
 
 
95
 
  AUTOMAKE=automake-1.9 ACLOCAL=aclocal-1.9 autoreconf -fvi
96
 
 
97
 
Make sure you're using the same version of automake and aclocal.
98
 
 
99
 
### Source Package: ###
100
 
Google Test is also released in source packages which can be downloaded from
101
 
its Google Code download page[1]. Several different archive formats are
102
 
provided, but the only difference is the tools used to manipulate them, and the
103
 
size 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
 
 
107
 
Once downloaded expand the archive using whichever tools you prefer for that
108
 
type. This will always result in a new directory with the name "gtest-X.Y.Z"
109
 
which 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
 
 
115
 
Choosing a TR1 Tuple Library
116
 
----------------------------
117
 
Some Google Test features require the C++ Technical Report 1 (TR1)
118
 
tuple library, which is not yet widely available with all compilers.
119
 
The good news is that Google Test implements a subset of TR1 tuple
120
 
that's enough for its own need, and will automatically use this when
121
 
the compiler doesn't provide TR1 tuple.
122
 
 
123
 
Usually you don't need to care about which tuple library Google Test
124
 
uses.  However, if your project already uses TR1 tuple, you need to
125
 
tell Google Test to use the same TR1 tuple library the rest of your
126
 
project uses (this requirement is new in Google Test 1.4.0, so you may
127
 
need to take care of it when upgrading from an earlier version), or
128
 
the two tuple implementations will clash.  To do that, add
129
 
 
130
 
  -DGTEST_USE_OWN_TR1_TUPLE=0
131
 
 
132
 
to the compiler flags while compiling Google Test and your tests.
133
 
 
134
 
If you don't want Google Test to use tuple at all, add
135
 
 
136
 
  -DGTEST_HAS_TR1_TUPLE=0
137
 
 
138
 
to the compiler flags.  All features using tuple will be disabled in
139
 
this mode.
140
 
 
141
 
Building the Source
142
 
-------------------
143
 
### Linux, Mac OS X (without Xcode), and Cygwin ###
144
 
There are two primary options for building the source at this point: build it
145
 
inside the source code tree, or in a separate directory. We recommend building
146
 
in a separate directory as that tends to produce both more consistent results
147
 
and be easier to clean up should anything go wrong, but both patterns are
148
 
supported. The only hard restriction is that while the build directory can be
149
 
a subdirectory of the source directory, the opposite is not possible and will
150
 
result in errors. Once you have selected where you wish to build Google Test,
151
 
create the directory if necessary, and enter it. The following steps apply for
152
 
either approach by simply substituting the shell variable SRCDIR with "." for
153
 
building inside the source directory, and the relative path to the source
154
 
directory otherwise.
155
 
 
156
 
  ${SRCDIR}/configure  # Standard GNU configure script, --help for more info
157
 
  make  # Standard makefile following GNU conventions
158
 
  make check  # Builds and runs all tests - all should pass
159
 
 
160
 
Other programs will only be able to use Google Test's functionality if you
161
 
install it in a location which they can access, in Linux this is typically
162
 
under '/usr/local'. The following command will install all of the Google Test
163
 
libraries, public headers, and utilities necessary for other programs and
164
 
libraries to leverage it:
165
 
 
166
 
  sudo make install  # Not necessary, but allows use by other programs
167
 
 
168
 
Should you need to remove Google Test from your system after having installed
169
 
it, run the following command, and it will back out its changes.  However, note
170
 
carefully that you must run this command on the *same* Google Test build that
171
 
you ran the install from, or the results are not predictable.  If you install
172
 
Google Test on your system, and are working from a VCS checkout, make sure you
173
 
run this *before* updating your checkout of the source in order to uninstall
174
 
the same version which you installed.
175
 
 
176
 
  sudo make uninstall  # Must be run against the exact same build as "install"
177
 
 
178
 
Your project can build against Google Test simply by leveraging the
179
 
'gtest-config' script. This script can be invoked directly out of the 'scripts'
180
 
subdirectory of the build tree, and it will be installed in the binary
181
 
directory specified during the 'configure'. Here are some examples of its use,
182
 
see 'gtest-config --help' for more detailed information.
183
 
 
184
 
  gtest-config --min-version=1.0 || echo "Insufficient Google Test version."
185
 
 
186
 
  g++ $(gtest-config --cppflags --cxxflags) -o foo.o -c foo.cpp
187
 
  g++ $(gtest-config --ldflags --libs) -o foo foo.o
188
 
 
189
 
  # When using a built but not installed Google Test:
190
 
  g++ $(../../my_gtest_build/scripts/gtest-config ...) ...
191
 
 
192
 
### Windows ###
193
 
The msvc\ folder contains two solutions with Visual C++ projects. Open the
194
 
gtest.sln or gtest-md.sln file using Visual Studio, and you are ready to
195
 
build Google Test the same way you build any Visual Studio project. Files
196
 
that have names ending with -md use DLL versions of Microsoft runtime
197
 
libraries (the /MD or the /MDd compiler option). Files without that suffix
198
 
use static versions of the runtime libraries (the /MT or the /MTd option).
199
 
Please note that one must use the same option to compile both gtest and his
200
 
test code. If you use Visual Studio 2005 or above, we recommend the -md
201
 
version as /MD is the default for new projects in these versions of Visual
202
 
Studio.
203
 
 
204
 
### Mac OS X (universal-binary framework) ###
205
 
Open the gtest.xcodeproj in the xcode/ folder using Xcode. Build the "gtest"
206
 
target. The universal binary framework will end up in your selected build
207
 
directory (selected in the Xcode "Preferences..." -> "Building" pane and
208
 
defaults to xcode/build). Alternatively, at the command line, enter:
209
 
 
210
 
  xcodebuild
211
 
 
212
 
This will build the "Release" configuration of gtest.framework in your
213
 
default build location. See the "xcodebuild" man page for more information about
214
 
building different configurations and building in different locations.
215
 
 
216
 
To test the gtest.framework in Xcode, change the active target to "Check" and
217
 
then build. This target builds all of the tests and then runs them. Don't worry
218
 
if you see some errors. Xcode reports all test failures (even the intentional
219
 
ones) as errors. However, you should see a "Build succeeded" message at the end
220
 
of the build log. To run all of the tests from the command line, enter:
221
 
 
222
 
  xcodebuild -target Check
223
 
 
224
 
Installation with xcodebuild requires specifying an installation desitination
225
 
directory, known as the DSTROOT. Three items will be installed when using
226
 
xcodebuild:
227
 
 
228
 
  $DSTROOT/Library/Frameworks/gtest.framework
229
 
  $DSTROOT/usr/local/lib/libgtest.a
230
 
  $DSTROOT/usr/local/lib/libgtest_main.a
231
 
 
232
 
You specify the installation directory on the command line with the other
233
 
xcodebuild options. Here's how you would install in a user-visible location:
234
 
 
235
 
  xcodebuild install DSTROOT=~
236
 
 
237
 
To perform a system-wide inistall, escalate to an administrator and specify
238
 
the file system root as the DSTROOT:
239
 
 
240
 
  sudo xcodebuild install DSTROOT=/
241
 
 
242
 
To uninstall gtest.framework via the command line, you need to delete the three
243
 
items listed above. Remember to escalate to an administrator if deleting these
244
 
from the system-wide location using the commands listed below:
245
 
 
246
 
  sudo rm -r /Library/Frameworks/gtest.framework
247
 
  sudo rm /usr/local/lib/libgtest.a
248
 
  sudo rm /usr/local/lib/libgtest_main.a
249
 
 
250
 
It is also possible to build and execute individual tests within Xcode. Each
251
 
test has its own Xcode "Target" and Xcode "Executable". To build any of the
252
 
tests, change the active target and the active executable to the test of
253
 
interest and then build and run.
254
 
 
255
 
Individual tests can be built from the command line using:
256
 
 
257
 
  xcodebuild -target <test_name>
258
 
 
259
 
These tests can be executed from the command line by moving to the build
260
 
directory and then (in bash)
261
 
 
262
 
  export DYLD_FRAMEWORK_PATH=`pwd`
263
 
  ./<test_name>  # (e.g. ./gtest_unittest)
264
 
 
265
 
To use gtest.framework for your own tests, first, install the framework using
266
 
the steps described above. Then add it to your Xcode project by selecting
267
 
Project->Add to Project... from the main menu. Next, add libgtest_main.a from
268
 
gtest.framework/Resources directory using the same menu command. Finally,
269
 
create a new executable target and add gtest.framework and libgtest_main.a to
270
 
the "Link Binary With Libraries" build phase.
271
 
 
272
 
### Using GNU Make ###
273
 
The make/ directory contains a Makefile that you can use to build
274
 
Google Test on systems where GNU make is available (e.g. Linux, Mac OS
275
 
X, and Cygwin).  It doesn't try to build Google Test's own tests.
276
 
Instead, it just builds the Google Test library and a sample test.
277
 
You can use it as a starting point for your own Makefile.
278
 
 
279
 
If the default settings are correct for your environment, the
280
 
following commands should succeed:
281
 
 
282
 
  cd ${SRCDIR}/make
283
 
  make
284
 
  ./sample1_unittest
285
 
 
286
 
If you see errors, try to tweak the contents of make/Makefile to make
287
 
them go away.  There are instructions in make/Makefile on how to do
288
 
it.
289
 
 
290
 
### Using Your Own Build System ###
291
 
If none of the build solutions we provide works for you, or if you
292
 
prefer your own build system, you just need to compile
293
 
src/gtest-all.cc into a library and link your tests with it.  Assuming
294
 
a Linux-like system and gcc, something like the following will do:
295
 
 
296
 
  cd ${SRCDIR}
297
 
  g++ -I. -I./include -c src/gtest-all.cc
298
 
  ar -rv libgtest.a gtest-all.o
299
 
  g++ -I. -I./include path/to/your_test.cc libgtest.a -o your_test
300
 
 
301
 
Regenerating Source Files
302
 
-------------------------
303
 
Some of Google Test's source files are generated from templates (not
304
 
in the C++ sense) using a script.  A template file is named FOO.pump,
305
 
where FOO is the name of the file it will generate.  For example, the
306
 
file include/gtest/internal/gtest-type-util.h.pump is used to generate
307
 
gtest-type-util.h in the same directory.
308
 
 
309
 
Normally you don't need to worry about regenerating the source files,
310
 
unless you need to modify them (e.g. if you are working on a patch for
311
 
Google Test).  In that case, you should modify the corresponding .pump
312
 
files instead and run the 'pump' script (for Pump is Useful for Meta
313
 
Programming) to regenerate them.  We are still working on releasing
314
 
the script and its documentation.  If you need it now, please email
315
 
googletestframework@googlegroups.com such that we know to make it
316
 
happen sooner.
317
 
 
318
 
Happy testing!