diff options
Diffstat (limited to 'testing/gtest/README')
| -rw-r--r-- | testing/gtest/README | 286 |
1 files changed, 286 insertions, 0 deletions
diff --git a/testing/gtest/README b/testing/gtest/README new file mode 100644 index 0000000..5205303 --- /dev/null +++ b/testing/gtest/README @@ -0,0 +1,286 @@ +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 + +### Windows ### +The msvc\ folder contains two solutions with Visual C++ projects. Open the +gtest.sln or gtest-md.sln file using Visual Studio, and you 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 his +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. + +### 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 gtest.framework in your +default build location. See the "xcodebuild" man page for more information about +building different configurations and building in different locations. + +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: + + xcodebuild -target Check + +Installation with xcodebuild requires specifying an installation desitination +directory, known as the DSTROOT. Three items will be installed when using +xcodebuild: + + $DSTROOT/Library/Frameworks/gtest.framework + $DSTROOT/usr/local/lib/libgtest.a + $DSTROOT/usr/local/lib/libgtest_main.a + +You specify the installation directory on the command line with the other +xcodebuild options. Here's how you would install in a user-visible location: + + xcodebuild install DSTROOT=~ + +To perform a system-wide inistall, escalate to an administrator and specify +the file system root as the DSTROOT: + + sudo xcodebuild install DSTROOT=/ + +To uninstall gtest.framework via the command line, you need to delete the three +items listed above. Remember to escalate to an administrator if deleting these +from the system-wide location using the commands listed below: + + sudo rm -r /Library/Frameworks/gtest.framework + sudo rm /usr/local/lib/libgtest.a + sudo rm /usr/local/lib/libgtest_main.a + +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. + +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> # (e.g. ./gtest_unittest) + +To use gtest.framework for your own tests, first, install the framework using +the steps described above. Then add it to your Xcode project by selecting +Project->Add to Project... from the main menu. Next, add libgtest_main.a from +gtest.framework/Resources directory using the same menu command. Finally, +create a new executable target and add gtest.framework and libgtest_main.a to +the "Link Binary With Libraries" build phase. + +### 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! |