113481Sgiacomo.travaglini@arm.com 213481Sgiacomo.travaglini@arm.com### Generic Build Instructions ### 313481Sgiacomo.travaglini@arm.com 413481Sgiacomo.travaglini@arm.com#### Setup #### 513481Sgiacomo.travaglini@arm.com 613481Sgiacomo.travaglini@arm.comTo build Google Test and your tests that use it, you need to tell your 713481Sgiacomo.travaglini@arm.combuild system where to find its headers and source files. The exact 813481Sgiacomo.travaglini@arm.comway to do it depends on which build system you use, and is usually 913481Sgiacomo.travaglini@arm.comstraightforward. 1013481Sgiacomo.travaglini@arm.com 1113481Sgiacomo.travaglini@arm.com#### Build #### 1213481Sgiacomo.travaglini@arm.com 1313481Sgiacomo.travaglini@arm.comSuppose you put Google Test in directory `${GTEST_DIR}`. To build it, 1413481Sgiacomo.travaglini@arm.comcreate a library build target (or a project as called by Visual Studio 1513481Sgiacomo.travaglini@arm.comand Xcode) to compile 1613481Sgiacomo.travaglini@arm.com 1713481Sgiacomo.travaglini@arm.com ${GTEST_DIR}/src/gtest-all.cc 1813481Sgiacomo.travaglini@arm.com 1913481Sgiacomo.travaglini@arm.comwith `${GTEST_DIR}/include` in the system header search path and `${GTEST_DIR}` 2013481Sgiacomo.travaglini@arm.comin the normal header search path. Assuming a Linux-like system and gcc, 2113481Sgiacomo.travaglini@arm.comsomething like the following will do: 2213481Sgiacomo.travaglini@arm.com 2313481Sgiacomo.travaglini@arm.com g++ -isystem ${GTEST_DIR}/include -I${GTEST_DIR} \ 2413481Sgiacomo.travaglini@arm.com -pthread -c ${GTEST_DIR}/src/gtest-all.cc 2513481Sgiacomo.travaglini@arm.com ar -rv libgtest.a gtest-all.o 2613481Sgiacomo.travaglini@arm.com 2713481Sgiacomo.travaglini@arm.com(We need `-pthread` as Google Test uses threads.) 2813481Sgiacomo.travaglini@arm.com 2913481Sgiacomo.travaglini@arm.comNext, you should compile your test source file with 3013481Sgiacomo.travaglini@arm.com`${GTEST_DIR}/include` in the system header search path, and link it 3113481Sgiacomo.travaglini@arm.comwith gtest and any other necessary libraries: 3213481Sgiacomo.travaglini@arm.com 3313481Sgiacomo.travaglini@arm.com g++ -isystem ${GTEST_DIR}/include -pthread path/to/your_test.cc libgtest.a \ 3413481Sgiacomo.travaglini@arm.com -o your_test 3513481Sgiacomo.travaglini@arm.com 3613481Sgiacomo.travaglini@arm.comAs an example, the make/ directory contains a Makefile that you can 3713481Sgiacomo.travaglini@arm.comuse to build Google Test on systems where GNU make is available 3813481Sgiacomo.travaglini@arm.com(e.g. Linux, Mac OS X, and Cygwin). It doesn't try to build Google 3913481Sgiacomo.travaglini@arm.comTest's own tests. Instead, it just builds the Google Test library and 4013481Sgiacomo.travaglini@arm.coma sample test. You can use it as a starting point for your own build 4113481Sgiacomo.travaglini@arm.comscript. 4213481Sgiacomo.travaglini@arm.com 4313481Sgiacomo.travaglini@arm.comIf the default settings are correct for your environment, the 4413481Sgiacomo.travaglini@arm.comfollowing commands should succeed: 4513481Sgiacomo.travaglini@arm.com 4613481Sgiacomo.travaglini@arm.com cd ${GTEST_DIR}/make 4713481Sgiacomo.travaglini@arm.com make 4813481Sgiacomo.travaglini@arm.com ./sample1_unittest 4913481Sgiacomo.travaglini@arm.com 5013481Sgiacomo.travaglini@arm.comIf you see errors, try to tweak the contents of `make/Makefile` to make 5113481Sgiacomo.travaglini@arm.comthem go away. There are instructions in `make/Makefile` on how to do 5213481Sgiacomo.travaglini@arm.comit. 5313481Sgiacomo.travaglini@arm.com 5413481Sgiacomo.travaglini@arm.com### Using CMake ### 5513481Sgiacomo.travaglini@arm.com 5613481Sgiacomo.travaglini@arm.comGoogle Test comes with a CMake build script ( 5713481Sgiacomo.travaglini@arm.com[CMakeLists.txt](CMakeLists.txt)) that can be used on a wide range of platforms ("C" stands for 5813481Sgiacomo.travaglini@arm.comcross-platform.). If you don't have CMake installed already, you can 5913481Sgiacomo.travaglini@arm.comdownload it for free from <http://www.cmake.org/>. 6013481Sgiacomo.travaglini@arm.com 6113481Sgiacomo.travaglini@arm.comCMake works by generating native makefiles or build projects that can 6213481Sgiacomo.travaglini@arm.combe used in the compiler environment of your choice. The typical 6313481Sgiacomo.travaglini@arm.comworkflow starts with: 6413481Sgiacomo.travaglini@arm.com 6513481Sgiacomo.travaglini@arm.com mkdir mybuild # Create a directory to hold the build output. 6613481Sgiacomo.travaglini@arm.com cd mybuild 6713481Sgiacomo.travaglini@arm.com cmake ${GTEST_DIR} # Generate native build scripts. 6813481Sgiacomo.travaglini@arm.com 6913481Sgiacomo.travaglini@arm.comIf you want to build Google Test's samples, you should replace the 7013481Sgiacomo.travaglini@arm.comlast command with 7113481Sgiacomo.travaglini@arm.com 7213481Sgiacomo.travaglini@arm.com cmake -Dgtest_build_samples=ON ${GTEST_DIR} 7313481Sgiacomo.travaglini@arm.com 7413481Sgiacomo.travaglini@arm.comIf you are on a \*nix system, you should now see a Makefile in the 7513481Sgiacomo.travaglini@arm.comcurrent directory. Just type 'make' to build gtest. 7613481Sgiacomo.travaglini@arm.com 7713481Sgiacomo.travaglini@arm.comIf you use Windows and have Visual Studio installed, a `gtest.sln` file 7813481Sgiacomo.travaglini@arm.comand several `.vcproj` files will be created. You can then build them 7913481Sgiacomo.travaglini@arm.comusing Visual Studio. 8013481Sgiacomo.travaglini@arm.com 8113481Sgiacomo.travaglini@arm.comOn Mac OS X with Xcode installed, a `.xcodeproj` file will be generated. 8213481Sgiacomo.travaglini@arm.com 8313481Sgiacomo.travaglini@arm.com### Legacy Build Scripts ### 8413481Sgiacomo.travaglini@arm.com 8513481Sgiacomo.travaglini@arm.comBefore settling on CMake, we have been providing hand-maintained build 8613481Sgiacomo.travaglini@arm.comprojects/scripts for Visual Studio, Xcode, and Autotools. While we 8713481Sgiacomo.travaglini@arm.comcontinue to provide them for convenience, they are not actively 8813481Sgiacomo.travaglini@arm.commaintained any more. We highly recommend that you follow the 8913481Sgiacomo.travaglini@arm.cominstructions in the previous two sections to integrate Google Test 9013481Sgiacomo.travaglini@arm.comwith your existing build system. 9113481Sgiacomo.travaglini@arm.com 9213481Sgiacomo.travaglini@arm.comIf you still need to use the legacy build scripts, here's how: 9313481Sgiacomo.travaglini@arm.com 9413481Sgiacomo.travaglini@arm.comThe msvc\ folder contains two solutions with Visual C++ projects. 9513481Sgiacomo.travaglini@arm.comOpen the `gtest.sln` or `gtest-md.sln` file using Visual Studio, and you 9613481Sgiacomo.travaglini@arm.comare ready to build Google Test the same way you build any Visual 9713481Sgiacomo.travaglini@arm.comStudio project. Files that have names ending with -md use DLL 9813481Sgiacomo.travaglini@arm.comversions of Microsoft runtime libraries (the /MD or the /MDd compiler 9913481Sgiacomo.travaglini@arm.comoption). Files without that suffix use static versions of the runtime 10013481Sgiacomo.travaglini@arm.comlibraries (the /MT or the /MTd option). Please note that one must use 10113481Sgiacomo.travaglini@arm.comthe same option to compile both gtest and the test code. If you use 10213481Sgiacomo.travaglini@arm.comVisual Studio 2005 or above, we recommend the -md version as /MD is 10313481Sgiacomo.travaglini@arm.comthe default for new projects in these versions of Visual Studio. 10413481Sgiacomo.travaglini@arm.com 10513481Sgiacomo.travaglini@arm.comOn Mac OS X, open the `gtest.xcodeproj` in the `xcode/` folder using 10613481Sgiacomo.travaglini@arm.comXcode. Build the "gtest" target. The universal binary framework will 10713481Sgiacomo.travaglini@arm.comend up in your selected build directory (selected in the Xcode 10813481Sgiacomo.travaglini@arm.com"Preferences..." -> "Building" pane and defaults to xcode/build). 10913481Sgiacomo.travaglini@arm.comAlternatively, at the command line, enter: 11013481Sgiacomo.travaglini@arm.com 11113481Sgiacomo.travaglini@arm.com xcodebuild 11213481Sgiacomo.travaglini@arm.com 11313481Sgiacomo.travaglini@arm.comThis will build the "Release" configuration of gtest.framework in your 11413481Sgiacomo.travaglini@arm.comdefault build location. See the "xcodebuild" man page for more 11513481Sgiacomo.travaglini@arm.cominformation about building different configurations and building in 11613481Sgiacomo.travaglini@arm.comdifferent locations. 11713481Sgiacomo.travaglini@arm.com 11813481Sgiacomo.travaglini@arm.comIf you wish to use the Google Test Xcode project with Xcode 4.x and 11913481Sgiacomo.travaglini@arm.comabove, you need to either: 12013481Sgiacomo.travaglini@arm.com 12113481Sgiacomo.travaglini@arm.com * update the SDK configuration options in xcode/Config/General.xconfig. 12213481Sgiacomo.travaglini@arm.com Comment options `SDKROOT`, `MACOS_DEPLOYMENT_TARGET`, and `GCC_VERSION`. If 12313481Sgiacomo.travaglini@arm.com you choose this route you lose the ability to target earlier versions 12413481Sgiacomo.travaglini@arm.com of MacOS X. 12513481Sgiacomo.travaglini@arm.com * Install an SDK for an earlier version. This doesn't appear to be 12613481Sgiacomo.travaglini@arm.com supported by Apple, but has been reported to work 12713481Sgiacomo.travaglini@arm.com (http://stackoverflow.com/questions/5378518). 12813481Sgiacomo.travaglini@arm.com 12913481Sgiacomo.travaglini@arm.com### Tweaking Google Test ### 13013481Sgiacomo.travaglini@arm.com 13113481Sgiacomo.travaglini@arm.comGoogle Test can be used in diverse environments. The default 13213481Sgiacomo.travaglini@arm.comconfiguration may not work (or may not work well) out of the box in 13313481Sgiacomo.travaglini@arm.comsome environments. However, you can easily tweak Google Test by 13413481Sgiacomo.travaglini@arm.comdefining control macros on the compiler command line. Generally, 13513481Sgiacomo.travaglini@arm.comthese macros are named like `GTEST_XYZ` and you define them to either 1 13613481Sgiacomo.travaglini@arm.comor 0 to enable or disable a certain feature. 13713481Sgiacomo.travaglini@arm.com 13813481Sgiacomo.travaglini@arm.comWe list the most frequently used macros below. For a complete list, 13913481Sgiacomo.travaglini@arm.comsee file [include/gtest/internal/gtest-port.h](include/gtest/internal/gtest-port.h). 14013481Sgiacomo.travaglini@arm.com 14113481Sgiacomo.travaglini@arm.com### Choosing a TR1 Tuple Library ### 14213481Sgiacomo.travaglini@arm.com 14313481Sgiacomo.travaglini@arm.comSome Google Test features require the C++ Technical Report 1 (TR1) 14413481Sgiacomo.travaglini@arm.comtuple library, which is not yet available with all compilers. The 14513481Sgiacomo.travaglini@arm.comgood news is that Google Test implements a subset of TR1 tuple that's 14613481Sgiacomo.travaglini@arm.comenough for its own need, and will automatically use this when the 14713481Sgiacomo.travaglini@arm.comcompiler doesn't provide TR1 tuple. 14813481Sgiacomo.travaglini@arm.com 14913481Sgiacomo.travaglini@arm.comUsually you don't need to care about which tuple library Google Test 15013481Sgiacomo.travaglini@arm.comuses. However, if your project already uses TR1 tuple, you need to 15113481Sgiacomo.travaglini@arm.comtell Google Test to use the same TR1 tuple library the rest of your 15213481Sgiacomo.travaglini@arm.comproject uses, or the two tuple implementations will clash. To do 15313481Sgiacomo.travaglini@arm.comthat, add 15413481Sgiacomo.travaglini@arm.com 15513481Sgiacomo.travaglini@arm.com -DGTEST_USE_OWN_TR1_TUPLE=0 15613481Sgiacomo.travaglini@arm.com 15713481Sgiacomo.travaglini@arm.comto the compiler flags while compiling Google Test and your tests. If 15813481Sgiacomo.travaglini@arm.comyou want to force Google Test to use its own tuple library, just add 15913481Sgiacomo.travaglini@arm.com 16013481Sgiacomo.travaglini@arm.com -DGTEST_USE_OWN_TR1_TUPLE=1 16113481Sgiacomo.travaglini@arm.com 16213481Sgiacomo.travaglini@arm.comto the compiler flags instead. 16313481Sgiacomo.travaglini@arm.com 16413481Sgiacomo.travaglini@arm.comIf you don't want Google Test to use tuple at all, add 16513481Sgiacomo.travaglini@arm.com 16613481Sgiacomo.travaglini@arm.com -DGTEST_HAS_TR1_TUPLE=0 16713481Sgiacomo.travaglini@arm.com 16813481Sgiacomo.travaglini@arm.comand all features using tuple will be disabled. 16913481Sgiacomo.travaglini@arm.com 17013481Sgiacomo.travaglini@arm.com### Multi-threaded Tests ### 17113481Sgiacomo.travaglini@arm.com 17213481Sgiacomo.travaglini@arm.comGoogle Test is thread-safe where the pthread library is available. 17313481Sgiacomo.travaglini@arm.comAfter `#include "gtest/gtest.h"`, you can check the `GTEST_IS_THREADSAFE` 17413481Sgiacomo.travaglini@arm.commacro to see whether this is the case (yes if the macro is `#defined` to 17513481Sgiacomo.travaglini@arm.com1, no if it's undefined.). 17613481Sgiacomo.travaglini@arm.com 17713481Sgiacomo.travaglini@arm.comIf Google Test doesn't correctly detect whether pthread is available 17813481Sgiacomo.travaglini@arm.comin your environment, you can force it with 17913481Sgiacomo.travaglini@arm.com 18013481Sgiacomo.travaglini@arm.com -DGTEST_HAS_PTHREAD=1 18113481Sgiacomo.travaglini@arm.com 18213481Sgiacomo.travaglini@arm.comor 18313481Sgiacomo.travaglini@arm.com 18413481Sgiacomo.travaglini@arm.com -DGTEST_HAS_PTHREAD=0 18513481Sgiacomo.travaglini@arm.com 18613481Sgiacomo.travaglini@arm.comWhen Google Test uses pthread, you may need to add flags to your 18713481Sgiacomo.travaglini@arm.comcompiler and/or linker to select the pthread library, or you'll get 18813481Sgiacomo.travaglini@arm.comlink errors. If you use the CMake script or the deprecated Autotools 18913481Sgiacomo.travaglini@arm.comscript, this is taken care of for you. If you use your own build 19013481Sgiacomo.travaglini@arm.comscript, you'll need to read your compiler and linker's manual to 19113481Sgiacomo.travaglini@arm.comfigure out what flags to add. 19213481Sgiacomo.travaglini@arm.com 19313481Sgiacomo.travaglini@arm.com### As a Shared Library (DLL) ### 19413481Sgiacomo.travaglini@arm.com 19513481Sgiacomo.travaglini@arm.comGoogle Test is compact, so most users can build and link it as a 19613481Sgiacomo.travaglini@arm.comstatic library for the simplicity. You can choose to use Google Test 19713481Sgiacomo.travaglini@arm.comas a shared library (known as a DLL on Windows) if you prefer. 19813481Sgiacomo.travaglini@arm.com 19913481Sgiacomo.travaglini@arm.comTo compile *gtest* as a shared library, add 20013481Sgiacomo.travaglini@arm.com 20113481Sgiacomo.travaglini@arm.com -DGTEST_CREATE_SHARED_LIBRARY=1 20213481Sgiacomo.travaglini@arm.com 20313481Sgiacomo.travaglini@arm.comto the compiler flags. You'll also need to tell the linker to produce 20413481Sgiacomo.travaglini@arm.coma shared library instead - consult your linker's manual for how to do 20513481Sgiacomo.travaglini@arm.comit. 20613481Sgiacomo.travaglini@arm.com 20713481Sgiacomo.travaglini@arm.comTo compile your *tests* that use the gtest shared library, add 20813481Sgiacomo.travaglini@arm.com 20913481Sgiacomo.travaglini@arm.com -DGTEST_LINKED_AS_SHARED_LIBRARY=1 21013481Sgiacomo.travaglini@arm.com 21113481Sgiacomo.travaglini@arm.comto the compiler flags. 21213481Sgiacomo.travaglini@arm.com 21313481Sgiacomo.travaglini@arm.comNote: while the above steps aren't technically necessary today when 21413481Sgiacomo.travaglini@arm.comusing some compilers (e.g. GCC), they may become necessary in the 21513481Sgiacomo.travaglini@arm.comfuture, if we decide to improve the speed of loading the library (see 21613481Sgiacomo.travaglini@arm.com<http://gcc.gnu.org/wiki/Visibility> for details). Therefore you are 21713481Sgiacomo.travaglini@arm.comrecommended to always add the above flags when using Google Test as a 21813481Sgiacomo.travaglini@arm.comshared library. Otherwise a future release of Google Test may break 21913481Sgiacomo.travaglini@arm.comyour build script. 22013481Sgiacomo.travaglini@arm.com 22113481Sgiacomo.travaglini@arm.com### Avoiding Macro Name Clashes ### 22213481Sgiacomo.travaglini@arm.com 22313481Sgiacomo.travaglini@arm.comIn C++, macros don't obey namespaces. Therefore two libraries that 22413481Sgiacomo.travaglini@arm.comboth define a macro of the same name will clash if you `#include` both 22513481Sgiacomo.travaglini@arm.comdefinitions. In case a Google Test macro clashes with another 22613481Sgiacomo.travaglini@arm.comlibrary, you can force Google Test to rename its macro to avoid the 22713481Sgiacomo.travaglini@arm.comconflict. 22813481Sgiacomo.travaglini@arm.com 22913481Sgiacomo.travaglini@arm.comSpecifically, if both Google Test and some other code define macro 23013481Sgiacomo.travaglini@arm.comFOO, you can add 23113481Sgiacomo.travaglini@arm.com 23213481Sgiacomo.travaglini@arm.com -DGTEST_DONT_DEFINE_FOO=1 23313481Sgiacomo.travaglini@arm.com 23413481Sgiacomo.travaglini@arm.comto the compiler flags to tell Google Test to change the macro's name 23513481Sgiacomo.travaglini@arm.comfrom `FOO` to `GTEST_FOO`. Currently `FOO` can be `FAIL`, `SUCCEED`, 23613481Sgiacomo.travaglini@arm.comor `TEST`. For example, with `-DGTEST_DONT_DEFINE_TEST=1`, you'll 23713481Sgiacomo.travaglini@arm.comneed to write 23813481Sgiacomo.travaglini@arm.com 23913481Sgiacomo.travaglini@arm.com GTEST_TEST(SomeTest, DoesThis) { ... } 24013481Sgiacomo.travaglini@arm.com 24113481Sgiacomo.travaglini@arm.cominstead of 24213481Sgiacomo.travaglini@arm.com 24313481Sgiacomo.travaglini@arm.com TEST(SomeTest, DoesThis) { ... } 24413481Sgiacomo.travaglini@arm.com 24513481Sgiacomo.travaglini@arm.comin order to define a test. 24613481Sgiacomo.travaglini@arm.com 24713481Sgiacomo.travaglini@arm.com## Developing Google Test ## 24813481Sgiacomo.travaglini@arm.com 24913481Sgiacomo.travaglini@arm.comThis section discusses how to make your own changes to Google Test. 25013481Sgiacomo.travaglini@arm.com 25113481Sgiacomo.travaglini@arm.com### Testing Google Test Itself ### 25213481Sgiacomo.travaglini@arm.com 25313481Sgiacomo.travaglini@arm.comTo make sure your changes work as intended and don't break existing 25413481Sgiacomo.travaglini@arm.comfunctionality, you'll want to compile and run Google Test's own tests. 25513481Sgiacomo.travaglini@arm.comFor that you can use CMake: 25613481Sgiacomo.travaglini@arm.com 25713481Sgiacomo.travaglini@arm.com mkdir mybuild 25813481Sgiacomo.travaglini@arm.com cd mybuild 25913481Sgiacomo.travaglini@arm.com cmake -Dgtest_build_tests=ON ${GTEST_DIR} 26013481Sgiacomo.travaglini@arm.com 26113481Sgiacomo.travaglini@arm.comMake sure you have Python installed, as some of Google Test's tests 26213481Sgiacomo.travaglini@arm.comare written in Python. If the cmake command complains about not being 26313481Sgiacomo.travaglini@arm.comable to find Python (`Could NOT find PythonInterp (missing: 26413481Sgiacomo.travaglini@arm.comPYTHON_EXECUTABLE)`), try telling it explicitly where your Python 26513481Sgiacomo.travaglini@arm.comexecutable can be found: 26613481Sgiacomo.travaglini@arm.com 26713481Sgiacomo.travaglini@arm.com cmake -DPYTHON_EXECUTABLE=path/to/python -Dgtest_build_tests=ON ${GTEST_DIR} 26813481Sgiacomo.travaglini@arm.com 26913481Sgiacomo.travaglini@arm.comNext, you can build Google Test and all of its own tests. On \*nix, 27013481Sgiacomo.travaglini@arm.comthis is usually done by 'make'. To run the tests, do 27113481Sgiacomo.travaglini@arm.com 27213481Sgiacomo.travaglini@arm.com make test 27313481Sgiacomo.travaglini@arm.com 27413481Sgiacomo.travaglini@arm.comAll tests should pass. 27513481Sgiacomo.travaglini@arm.com 27613481Sgiacomo.travaglini@arm.comNormally you don't need to worry about regenerating the source files, 27713481Sgiacomo.travaglini@arm.comunless you need to modify them. In that case, you should modify the 27813481Sgiacomo.travaglini@arm.comcorresponding .pump files instead and run the pump.py Python script to 27913481Sgiacomo.travaglini@arm.comregenerate them. You can find pump.py in the [scripts/](scripts/) directory. 28013481Sgiacomo.travaglini@arm.comRead the [Pump manual](docs/PumpManual.md) for how to use it. 281