|
| 1 | + |
| 2 | +### Generic Build Instructions ### |
| 3 | + |
| 4 | +#### Setup #### |
| 5 | + |
| 6 | +To build Google Test and your tests that use it, you need to tell your |
| 7 | +build system where to find its headers and source files. The exact |
| 8 | +way to do it depends on which build system you use, and is usually |
| 9 | +straightforward. |
| 10 | + |
| 11 | +#### Build #### |
| 12 | + |
| 13 | +Suppose you put Google Test in directory `${GTEST_DIR}`. To build it, |
| 14 | +create a library build target (or a project as called by Visual Studio |
| 15 | +and Xcode) to compile |
| 16 | + |
| 17 | + ${GTEST_DIR}/src/gtest-all.cc |
| 18 | + |
| 19 | +with `${GTEST_DIR}/include` in the system header search path and `${GTEST_DIR}` |
| 20 | +in the normal header search path. Assuming a Linux-like system and gcc, |
| 21 | +something like the following will do: |
| 22 | + |
| 23 | + g++ -isystem ${GTEST_DIR}/include -I${GTEST_DIR} \ |
| 24 | + -pthread -c ${GTEST_DIR}/src/gtest-all.cc |
| 25 | + ar -rv libgtest.a gtest-all.o |
| 26 | + |
| 27 | +(We need `-pthread` as Google Test uses threads.) |
| 28 | + |
| 29 | +Next, you should compile your test source file with |
| 30 | +`${GTEST_DIR}/include` in the system header search path, and link it |
| 31 | +with gtest and any other necessary libraries: |
| 32 | + |
| 33 | + g++ -isystem ${GTEST_DIR}/include -pthread path/to/your_test.cc libgtest.a \ |
| 34 | + -o your_test |
| 35 | + |
| 36 | +As an example, the make/ directory contains a Makefile that you can |
| 37 | +use to build Google Test on systems where GNU make is available |
| 38 | +(e.g. Linux, Mac OS X, and Cygwin). It doesn't try to build Google |
| 39 | +Test's own tests. Instead, it just builds the Google Test library and |
| 40 | +a sample test. You can use it as a starting point for your own build |
| 41 | +script. |
| 42 | + |
| 43 | +If the default settings are correct for your environment, the |
| 44 | +following commands should succeed: |
| 45 | + |
| 46 | + cd ${GTEST_DIR}/make |
| 47 | + make |
| 48 | + ./sample1_unittest |
| 49 | + |
| 50 | +If you see errors, try to tweak the contents of `make/Makefile` to make |
| 51 | +them go away. There are instructions in `make/Makefile` on how to do |
| 52 | +it. |
| 53 | + |
| 54 | +### Using CMake ### |
| 55 | + |
| 56 | +Google Test comes with a CMake build script ( |
| 57 | +[CMakeLists.txt](CMakeLists.txt)) that can be used on a wide range of platforms ("C" stands for |
| 58 | +cross-platform.). If you don't have CMake installed already, you can |
| 59 | +download it for free from <http://www.cmake.org/>. |
| 60 | + |
| 61 | +CMake works by generating native makefiles or build projects that can |
| 62 | +be used in the compiler environment of your choice. The typical |
| 63 | +workflow starts with: |
| 64 | + |
| 65 | + mkdir mybuild # Create a directory to hold the build output. |
| 66 | + cd mybuild |
| 67 | + cmake ${GTEST_DIR} # Generate native build scripts. |
| 68 | + |
| 69 | +If you want to build Google Test's samples, you should replace the |
| 70 | +last command with |
| 71 | + |
| 72 | + cmake -Dgtest_build_samples=ON ${GTEST_DIR} |
| 73 | + |
| 74 | +If you are on a \*nix system, you should now see a Makefile in the |
| 75 | +current directory. Just type 'make' to build gtest. |
| 76 | + |
| 77 | +If you use Windows and have Visual Studio installed, a `gtest.sln` file |
| 78 | +and several `.vcproj` files will be created. You can then build them |
| 79 | +using Visual Studio. |
| 80 | + |
| 81 | +On Mac OS X with Xcode installed, a `.xcodeproj` file will be generated. |
| 82 | + |
| 83 | +### Legacy Build Scripts ### |
| 84 | + |
| 85 | +Before settling on CMake, we have been providing hand-maintained build |
| 86 | +projects/scripts for Visual Studio, Xcode, and Autotools. While we |
| 87 | +continue to provide them for convenience, they are not actively |
| 88 | +maintained any more. We highly recommend that you follow the |
| 89 | +instructions in the previous two sections to integrate Google Test |
| 90 | +with your existing build system. |
| 91 | + |
| 92 | +If you still need to use the legacy build scripts, here's how: |
| 93 | + |
| 94 | +The msvc\ folder contains two solutions with Visual C++ projects. |
| 95 | +Open the `gtest.sln` or `gtest-md.sln` file using Visual Studio, and you |
| 96 | +are ready to build Google Test the same way you build any Visual |
| 97 | +Studio project. Files that have names ending with -md use DLL |
| 98 | +versions of Microsoft runtime libraries (the /MD or the /MDd compiler |
| 99 | +option). Files without that suffix use static versions of the runtime |
| 100 | +libraries (the /MT or the /MTd option). Please note that one must use |
| 101 | +the same option to compile both gtest and the test code. If you use |
| 102 | +Visual Studio 2005 or above, we recommend the -md version as /MD is |
| 103 | +the default for new projects in these versions of Visual Studio. |
| 104 | + |
| 105 | +On Mac OS X, open the `gtest.xcodeproj` in the `xcode/` folder using |
| 106 | +Xcode. Build the "gtest" target. The universal binary framework will |
| 107 | +end up in your selected build directory (selected in the Xcode |
| 108 | +"Preferences..." -> "Building" pane and defaults to xcode/build). |
| 109 | +Alternatively, at the command line, enter: |
| 110 | + |
| 111 | + xcodebuild |
| 112 | + |
| 113 | +This will build the "Release" configuration of gtest.framework in your |
| 114 | +default build location. See the "xcodebuild" man page for more |
| 115 | +information about building different configurations and building in |
| 116 | +different locations. |
| 117 | + |
| 118 | +If you wish to use the Google Test Xcode project with Xcode 4.x and |
| 119 | +above, you need to either: |
| 120 | + |
| 121 | + * update the SDK configuration options in xcode/Config/General.xconfig. |
| 122 | + Comment options `SDKROOT`, `MACOS_DEPLOYMENT_TARGET`, and `GCC_VERSION`. If |
| 123 | + you choose this route you lose the ability to target earlier versions |
| 124 | + of MacOS X. |
| 125 | + * Install an SDK for an earlier version. This doesn't appear to be |
| 126 | + supported by Apple, but has been reported to work |
| 127 | + (http://stackoverflow.com/questions/5378518). |
| 128 | + |
| 129 | +### Tweaking Google Test ### |
| 130 | + |
| 131 | +Google Test can be used in diverse environments. The default |
| 132 | +configuration may not work (or may not work well) out of the box in |
| 133 | +some environments. However, you can easily tweak Google Test by |
| 134 | +defining control macros on the compiler command line. Generally, |
| 135 | +these macros are named like `GTEST_XYZ` and you define them to either 1 |
| 136 | +or 0 to enable or disable a certain feature. |
| 137 | + |
| 138 | +We list the most frequently used macros below. For a complete list, |
| 139 | +see file [include/gtest/internal/gtest-port.h](include/gtest/internal/gtest-port.h). |
| 140 | + |
| 141 | +### Choosing a TR1 Tuple Library ### |
| 142 | + |
| 143 | +Some Google Test features require the C++ Technical Report 1 (TR1) |
| 144 | +tuple library, which is not yet available with all compilers. The |
| 145 | +good news is that Google Test implements a subset of TR1 tuple that's |
| 146 | +enough for its own need, and will automatically use this when the |
| 147 | +compiler doesn't provide TR1 tuple. |
| 148 | + |
| 149 | +Usually you don't need to care about which tuple library Google Test |
| 150 | +uses. However, if your project already uses TR1 tuple, you need to |
| 151 | +tell Google Test to use the same TR1 tuple library the rest of your |
| 152 | +project uses, or the two tuple implementations will clash. To do |
| 153 | +that, add |
| 154 | + |
| 155 | + -DGTEST_USE_OWN_TR1_TUPLE=0 |
| 156 | + |
| 157 | +to the compiler flags while compiling Google Test and your tests. If |
| 158 | +you want to force Google Test to use its own tuple library, just add |
| 159 | + |
| 160 | + -DGTEST_USE_OWN_TR1_TUPLE=1 |
| 161 | + |
| 162 | +to the compiler flags instead. |
| 163 | + |
| 164 | +If you don't want Google Test to use tuple at all, add |
| 165 | + |
| 166 | + -DGTEST_HAS_TR1_TUPLE=0 |
| 167 | + |
| 168 | +and all features using tuple will be disabled. |
| 169 | + |
| 170 | +### Multi-threaded Tests ### |
| 171 | + |
| 172 | +Google Test is thread-safe where the pthread library is available. |
| 173 | +After `#include "gtest/gtest.h"`, you can check the `GTEST_IS_THREADSAFE` |
| 174 | +macro to see whether this is the case (yes if the macro is `#defined` to |
| 175 | +1, no if it's undefined.). |
| 176 | + |
| 177 | +If Google Test doesn't correctly detect whether pthread is available |
| 178 | +in your environment, you can force it with |
| 179 | + |
| 180 | + -DGTEST_HAS_PTHREAD=1 |
| 181 | + |
| 182 | +or |
| 183 | + |
| 184 | + -DGTEST_HAS_PTHREAD=0 |
| 185 | + |
| 186 | +When Google Test uses pthread, you may need to add flags to your |
| 187 | +compiler and/or linker to select the pthread library, or you'll get |
| 188 | +link errors. If you use the CMake script or the deprecated Autotools |
| 189 | +script, this is taken care of for you. If you use your own build |
| 190 | +script, you'll need to read your compiler and linker's manual to |
| 191 | +figure out what flags to add. |
| 192 | + |
| 193 | +### As a Shared Library (DLL) ### |
| 194 | + |
| 195 | +Google Test is compact, so most users can build and link it as a |
| 196 | +static library for the simplicity. You can choose to use Google Test |
| 197 | +as a shared library (known as a DLL on Windows) if you prefer. |
| 198 | + |
| 199 | +To compile *gtest* as a shared library, add |
| 200 | + |
| 201 | + -DGTEST_CREATE_SHARED_LIBRARY=1 |
| 202 | + |
| 203 | +to the compiler flags. You'll also need to tell the linker to produce |
| 204 | +a shared library instead - consult your linker's manual for how to do |
| 205 | +it. |
| 206 | + |
| 207 | +To compile your *tests* that use the gtest shared library, add |
| 208 | + |
| 209 | + -DGTEST_LINKED_AS_SHARED_LIBRARY=1 |
| 210 | + |
| 211 | +to the compiler flags. |
| 212 | + |
| 213 | +Note: while the above steps aren't technically necessary today when |
| 214 | +using some compilers (e.g. GCC), they may become necessary in the |
| 215 | +future, if we decide to improve the speed of loading the library (see |
| 216 | +<http://gcc.gnu.org/wiki/Visibility> for details). Therefore you are |
| 217 | +recommended to always add the above flags when using Google Test as a |
| 218 | +shared library. Otherwise a future release of Google Test may break |
| 219 | +your build script. |
| 220 | + |
| 221 | +### Avoiding Macro Name Clashes ### |
| 222 | + |
| 223 | +In C++, macros don't obey namespaces. Therefore two libraries that |
| 224 | +both define a macro of the same name will clash if you `#include` both |
| 225 | +definitions. In case a Google Test macro clashes with another |
| 226 | +library, you can force Google Test to rename its macro to avoid the |
| 227 | +conflict. |
| 228 | + |
| 229 | +Specifically, if both Google Test and some other code define macro |
| 230 | +FOO, you can add |
| 231 | + |
| 232 | + -DGTEST_DONT_DEFINE_FOO=1 |
| 233 | + |
| 234 | +to the compiler flags to tell Google Test to change the macro's name |
| 235 | +from `FOO` to `GTEST_FOO`. Currently `FOO` can be `FAIL`, `SUCCEED`, |
| 236 | +or `TEST`. For example, with `-DGTEST_DONT_DEFINE_TEST=1`, you'll |
| 237 | +need to write |
| 238 | + |
| 239 | + GTEST_TEST(SomeTest, DoesThis) { ... } |
| 240 | + |
| 241 | +instead of |
| 242 | + |
| 243 | + TEST(SomeTest, DoesThis) { ... } |
| 244 | + |
| 245 | +in order to define a test. |
| 246 | + |
| 247 | +## Developing Google Test ## |
| 248 | + |
| 249 | +This section discusses how to make your own changes to Google Test. |
| 250 | + |
| 251 | +### Testing Google Test Itself ### |
| 252 | + |
| 253 | +To make sure your changes work as intended and don't break existing |
| 254 | +functionality, you'll want to compile and run Google Test's own tests. |
| 255 | +For that you can use CMake: |
| 256 | + |
| 257 | + mkdir mybuild |
| 258 | + cd mybuild |
| 259 | + cmake -Dgtest_build_tests=ON ${GTEST_DIR} |
| 260 | + |
| 261 | +Make sure you have Python installed, as some of Google Test's tests |
| 262 | +are written in Python. If the cmake command complains about not being |
| 263 | +able to find Python (`Could NOT find PythonInterp (missing: |
| 264 | +PYTHON_EXECUTABLE)`), try telling it explicitly where your Python |
| 265 | +executable can be found: |
| 266 | + |
| 267 | + cmake -DPYTHON_EXECUTABLE=path/to/python -Dgtest_build_tests=ON ${GTEST_DIR} |
| 268 | + |
| 269 | +Next, you can build Google Test and all of its own tests. On \*nix, |
| 270 | +this is usually done by 'make'. To run the tests, do |
| 271 | + |
| 272 | + make test |
| 273 | + |
| 274 | +All tests should pass. |
| 275 | + |
| 276 | +Normally you don't need to worry about regenerating the source files, |
| 277 | +unless you need to modify them. In that case, you should modify the |
| 278 | +corresponding .pump files instead and run the pump.py Python script to |
| 279 | +regenerate them. You can find pump.py in the [scripts/](scripts/) directory. |
| 280 | +Read the [Pump manual](docs/PumpManual.md) for how to use it. |
0 commit comments