diff options
Diffstat (limited to 'gtest/README')
| -rw-r--r-- | gtest/README | 300 |
1 files changed, 300 insertions, 0 deletions
diff --git a/gtest/README b/gtest/README new file mode 100644 index 0000000..cb8d4de --- /dev/null +++ b/gtest/README @@ -0,0 +1,300 @@ +Google C++ Testing Framework +============================ +http://code.google.com/p/googletest/ + +Overview +-------- +Google's framework for writing C++ tests on a variety of platforms (Linux, Mac +OS X, Windows, Windows CE, Symbian, and 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 mailing lists +for questions, discussions, and development. There is also an IRC channel on +OFTC (irc.oftc.net) #gtest available. Please join us! + +Requirements +------------ +Google Test is designed to have fairly minimal requirements to build +and use with your projects, but there are some. Currently, we support +building Google Test on Linux, Windows, Mac OS X, and Cygwin. We will +also make our best effort to support other platforms (e.g. Solaris and +IBM z/OS). However, since core members of the Google Test project +have no access to them, Google Test may have outstanding issues on +these platforms. If you notice any problems on your platform, please +notify googletestframework@googlegroups.com (patches for fixing them +are even more welcome!). + +### Linux Requirements ### +These are the base requirements to build and use Google Test from a source +package (as described below): + * GNU-compatible Make or "gmake" + * POSIX-standard shell + * POSIX(-2) Regular Expressions (regex.h) + * A C++98 standards compliant compiler + +Furthermore, if you are building Google Test from a VCS Checkout (also +described below), there are further requirements: + * Automake version 1.9 or newer + * Autoconf version 2.59 or newer + * Libtool / Libtoolize + * Python version 2.4 or newer + +### Windows Requirements ### + * Microsoft Visual Studio 7.1 or newer + +### Cygwin Requirements ### + * Cygwin 1.5.25-14 or newer + +### Mac OS X Requirements ### + * Mac OS X 10.4 Tiger or newer + * Developer Tools Installed + * Optional: Xcode 2.5 or later for univeral-binary framework; see note below. + +Getting the Source +------------------ +There are two primary ways of getting Google Test's source code: you can +download a source release in your preferred archive format, or directly check +out the source from a Version Control System (VCS, we use Google Code's +Subversion hosting). The VCS checkout requires a few extra steps and some extra +software packages on your system, but lets you track development, and make +patches to contribute much more easily, so we highly encourage it. + +### VCS Checkout: ### +The first step is to select whether you want to check out the main line of +development on Google Test, or one of the released branches. The former will be +much more active and have the latest features, but the latter provides much +more stability and predictability. Choose whichever fits your needs best, and +proceed with the following Subversion commands: + + svn checkout http://googletest.googlecode.com/svn/trunk/ gtest-svn + +or for a release version X.Y.*'s branch: + + svn checkout http://googletest.googlecode.com/svn/branches/release-X.Y/ \ + gtest-X.Y-svn + +Next you will need to prepare the GNU Autotools build system, if you +are using Linux, Mac OS X, or Cygwin. Enter the target directory of +the checkout command you used ('gtest-svn' or 'gtest-X.Y-svn' above) +and proceed with the following command: + + autoreconf -fvi + +Once you have completed this step, you are ready to build the library. Note +that you should only need to complete this step once. The subsequent `make' +invocations will automatically re-generate the bits of the build system that +need to be changed. + +If your system uses older versions of the autotools, the above command will +fail. You may need to explicitly specify a version to use. For instance, if you +have both GNU Automake 1.4 and 1.9 installed and `automake' would invoke the +1.4, use instead: + + AUTOMAKE=automake-1.9 ACLOCAL=aclocal-1.9 autoreconf -fvi + +Make sure you're using the same version of automake and aclocal. + +### Source Package: ### +Google Test is also released in source packages which can be downloaded from +its Google Code download page[1]. Several different archive formats are +provided, but the only difference is the tools used to manipulate them, and the +size of the resulting file. Download whichever you are most comfortable with. + + [1] Google Test Downloads: http://code.google.com/p/googletest/downloads/list + +Once downloaded expand the archive using whichever tools you prefer for that +type. This will always result in a new directory with the name "gtest-X.Y.Z" +which contains all of the source code. Here are some examples in Linux: + + tar -xvzf gtest-X.Y.Z.tar.gz + tar -xvjf gtest-X.Y.Z.tar.bz2 + unzip gtest-X.Y.Z.zip + +Choosing a TR1 Tuple Library +---------------------------- +Some Google Test features require the C++ Technical Report 1 (TR1) +tuple library, which is not yet widely 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. + +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 +project uses (this requirement is new in Google Test 1.4.0, so you may +need to take care of it when upgrading from an earlier version), or +the two tuple implementations will clash. To do that, add + + -DGTEST_USE_OWN_TR1_TUPLE=0 + +to the compiler flags while compiling Google Test and your tests. + +If you don't want Google Test to use tuple at all, add + + -DGTEST_HAS_TR1_TUPLE=0 + +to the compiler flags. All features using tuple will be disabled in +this mode. + +Building the Source +------------------- +### Linux, Mac OS X (without Xcode), and Cygwin ### +There are two primary options for building the source at this point: build it +inside the source code tree, or in a separate directory. We recommend building +in a separate directory as that tends to produce both more consistent results +and be easier to clean up should anything go wrong, but both patterns are +supported. The only hard restriction is that while the build directory can be +a subdirectory of the source directory, the opposite is not possible and will +result in errors. Once you have selected where you wish to build Google Test, +create the directory if necessary, and enter it. The following steps apply for +either approach by simply substituting the shell variable SRCDIR with "." for +building inside the source directory, and the relative path to the source +directory otherwise. + + ${SRCDIR}/configure # Standard GNU configure script, --help for more info + make # Standard makefile following GNU conventions + make check # Builds and runs all tests - all should pass + +Other programs will only be able to use Google Test's functionality if you +install it in a location which they can access, in Linux this is typically +under '/usr/local'. The following command will install all of the Google Test +libraries, public headers, and utilities necessary for other programs and +libraries to leverage it: + + sudo make install # Not necessary, but allows use by other programs + +Should you need to remove Google Test from your system after having installed +it, run the following command, and it will back out its changes. However, note +carefully that you must run this command on the *same* Google Test build that +you ran the install from, or the results are not predictable. If you install +Google Test on your system, and are working from a VCS checkout, make sure you +run this *before* updating your checkout of the source in order to uninstall +the same version which you installed. + + sudo make uninstall # Must be run against the exact same build as "install" + +Your project can build against Google Test simply by leveraging the +'gtest-config' script. This script can be invoked directly out of the 'scripts' +subdirectory of the build tree, and it will be installed in the binary +directory specified during the 'configure'. Here are some examples of its use, +see 'gtest-config --help' for more detailed information. + + gtest-config --min-version=1.0 || echo "Insufficient Google Test version." + + g++ $(gtest-config --cppflags --cxxflags) -o foo.o -c foo.cpp + g++ $(gtest-config --ldflags --libs) -o foo foo.o + + # When using a built but not installed Google Test: + g++ $(../../my_gtest_build/scripts/gtest-config ...) ... + +### Windows ### +Open the gtest.sln file in the msvc/ folder using Visual Studio, and +you are ready to build Google Test the same way you build any Visual +Studio project. + +### Mac OS X (universal-binary framework) ### +Open the gtest.xcodeproj in the xcode/ folder using 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: + + xcodebuild + +This will build the "Release" configuration of the gtest.framework, but you can +select the "Debug" configuration with a command line option. See the +"xcodebuild" man page for more information. + +To test the gtest.framework in Xcode, change the active target to "Check" and +then build. This target builds all of the tests and then runs them. Don't worry +if you see some errors. Xcode reports all test failures (even the intentional +ones) as errors. However, you should see a "Build succeeded" message at the end +of the build log. To run all of the tests from the command line, enter: + + xcodebuid -target Check + +It is also possible to build and execute individual tests within Xcode. Each +test has its own Xcode "Target" and Xcode "Executable". To build any of the +tests, change the active target and the active executable to the test of +interest and then build and run. + +NOTE: Several tests use a Python script to run the test executable. These can be +run from Xcode by creating a "Custom Executable". For example, to run the Python +script which executes the gtest_color_test, select the Project->New Custom +Executable... menu item. When prompted, set the "Executable Name" to something +like "run_gtest_color_test" and set the "Executable Path" to the path of the +gtest_color_test.py script. Finally, choose "Run" from the Run menu and check +the Console for the results. + +Individual tests can be built from the command line using: + + xcodebuild -target <test_name> + +These tests can be executed from the command line by moving to the build +directory and then (in bash) + + export DYLD_FRAMEWORK_PATH=`pwd` + ./<test_name> # (if it is not a python test, e.g. ./gtest_unittest) + # OR + ./<test_name>.py # (if it is a python test, e.g. ./gtest_color_test.py) + +To use the gtest.framework for your own tests, first, add the framework to Xcode +project. Next, create a new executable target and add the framework to the +"Link Binary With Libraries" build phase. Select "Edit Active Executable" from +the "Project" menu. In the "Arguments" tab, add + + "DYLD_FRAMEWORK_PATH" : "/real/framework/path" + +in the "Variables to be set in the environment:" list, where you replace +"/real/framework/path" with the actual location of the gtest.framework. Now +when you run your executable, it will load the framework and your test will +run as expected. + +### Using GNU Make ### +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 Makefile. + +If the default settings are correct for your environment, the +following commands should succeed: + + cd ${SRCDIR}/make + make + ./sample1_unittest + +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 +it. + +### Using Your Own Build System ### +If none of the build solutions we provide works for you, or if you +prefer your own build system, you just need to compile +src/gtest-all.cc into a library and link your tests with it. Assuming +a Linux-like system and gcc, something like the following will do: + + cd ${SRCDIR} + g++ -I. -I./include -c src/gtest-all.cc + ar -rv libgtest.a gtest-all.o + g++ -I. -I./include path/to/your_test.cc libgtest.a -o your_test + +Regenerating Source Files +------------------------- +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, +unless you need to modify them (e.g. if you are working on a patch for +Google Test). In that case, you should modify the corresponding .pump +files instead and run the 'pump' script (for Pump is Useful for Meta +Programming) to regenerate them. We are still working on releasing +the script and its documentation. If you need it now, please email +googletestframework@googlegroups.com such that we know to make it +happen sooner. + +Happy testing! |