|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360 |
-
- ### Generic Build Instructions ###
-
- #### Setup ####
-
- To build Google Test and your tests that use it, you need to tell your
- build system where to find its headers and source files. The exact
- way to do it depends on which build system you use, and is usually
- straightforward.
-
- #### Build ####
-
- Suppose you put Google Test in directory `${GTEST_DIR}`. To build it,
- create a library build target (or a project as called by Visual Studio
- and Xcode) to compile
-
- ${GTEST_DIR}/src/gtest-all.cc
-
- with `${GTEST_DIR}/include` in the system header search path and `${GTEST_DIR}`
- in the normal header search path. Assuming a Linux-like system and gcc,
- something like the following will do:
-
- g++ -isystem ${GTEST_DIR}/include -I${GTEST_DIR} \
- -pthread -c ${GTEST_DIR}/src/gtest-all.cc
- ar -rv libgtest.a gtest-all.o
-
- (We need `-pthread` as Google Test uses threads.)
-
- Next, you should compile your test source file with
- `${GTEST_DIR}/include` in the system header search path, and link it
- with gtest and any other necessary libraries:
-
- g++ -isystem ${GTEST_DIR}/include -pthread path/to/your_test.cc libgtest.a \
- -o your_test
-
- As an example, 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 build
- script.
-
- If the default settings are correct for your environment, the
- following commands should succeed:
-
- cd ${GTEST_DIR}/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 CMake ###
-
- Google Test comes with a CMake build script (
- [CMakeLists.txt](CMakeLists.txt)) that can be used on a wide range of platforms ("C" stands for
- cross-platform.). If you don't have CMake installed already, you can
- download it for free from <http://www.cmake.org/>.
-
- CMake works by generating native makefiles or build projects that can
- be used in the compiler environment of your choice. You can either
- build Google Test as a standalone project or it can be incorporated
- into an existing CMake build for another project.
-
- #### Standalone CMake Project ####
-
- When building Google Test as a standalone project, the typical
- workflow starts with:
-
- mkdir mybuild # Create a directory to hold the build output.
- cd mybuild
- cmake ${GTEST_DIR} # Generate native build scripts.
-
- If you want to build Google Test's samples, you should replace the
- last command with
-
- cmake -Dgtest_build_samples=ON ${GTEST_DIR}
-
- If you are on a \*nix system, you should now see a Makefile in the
- current directory. Just type 'make' to build gtest.
-
- If you use Windows and have Visual Studio installed, a `gtest.sln` file
- and several `.vcproj` files will be created. You can then build them
- using Visual Studio.
-
- On Mac OS X with Xcode installed, a `.xcodeproj` file will be generated.
-
- #### Incorporating Into An Existing CMake Project ####
-
- If you want to use gtest in a project which already uses CMake, then a
- more robust and flexible approach is to build gtest as part of that
- project directly. This is done by making the GoogleTest source code
- available to the main build and adding it using CMake's
- `add_subdirectory()` command. This has the significant advantage that
- the same compiler and linker settings are used between gtest and the
- rest of your project, so issues associated with using incompatible
- libraries (eg debug/release), etc. are avoided. This is particularly
- useful on Windows. Making GoogleTest's source code available to the
- main build can be done a few different ways:
-
- * Download the GoogleTest source code manually and place it at a
- known location. This is the least flexible approach and can make
- it more difficult to use with continuous integration systems, etc.
- * Embed the GoogleTest source code as a direct copy in the main
- project's source tree. This is often the simplest approach, but is
- also the hardest to keep up to date. Some organizations may not
- permit this method.
- * Add GoogleTest as a git submodule or equivalent. This may not
- always be possible or appropriate. Git submodules, for example,
- have their own set of advantages and drawbacks.
- * Use CMake to download GoogleTest as part of the build's configure
- step. This is just a little more complex, but doesn't have the
- limitations of the other methods.
-
- The last of the above methods is implemented with a small piece
- of CMake code in a separate file (e.g. `CMakeLists.txt.in`) which
- is copied to the build area and then invoked as a sub-build
- _during the CMake stage_. That directory is then pulled into the
- main build with `add_subdirectory()`. For example:
-
- New file `CMakeLists.txt.in`:
-
- cmake_minimum_required(VERSION 2.8.2)
-
- project(googletest-download NONE)
-
- include(ExternalProject)
- ExternalProject_Add(googletest
- GIT_REPOSITORY https://github.com/google/googletest.git
- GIT_TAG master
- SOURCE_DIR "${CMAKE_BINARY_DIR}/googletest-src"
- BINARY_DIR "${CMAKE_BINARY_DIR}/googletest-build"
- CONFIGURE_COMMAND ""
- BUILD_COMMAND ""
- INSTALL_COMMAND ""
- TEST_COMMAND ""
- )
-
- Existing build's `CMakeLists.txt`:
-
- # Download and unpack googletest at configure time
- configure_file(CMakeLists.txt.in googletest-download/CMakeLists.txt)
- execute_process(COMMAND ${CMAKE_COMMAND} -G "${CMAKE_GENERATOR}" .
- RESULT_VARIABLE result
- WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/googletest-download )
- if(result)
- message(FATAL_ERROR "CMake step for googletest failed: ${result}")
- endif()
- execute_process(COMMAND ${CMAKE_COMMAND} --build .
- RESULT_VARIABLE result
- WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/googletest-download )
- if(result)
- message(FATAL_ERROR "Build step for googletest failed: ${result}")
- endif()
-
- # Prevent overriding the parent project's compiler/linker
- # settings on Windows
- set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
-
- # Add googletest directly to our build. This defines
- # the gtest and gtest_main targets.
- add_subdirectory(${CMAKE_BINARY_DIR}/googletest-src
- ${CMAKE_BINARY_DIR}/googletest-build
- EXCLUDE_FROM_ALL)
-
- # The gtest/gtest_main targets carry header search path
- # dependencies automatically when using CMake 2.8.11 or
- # later. Otherwise we have to add them here ourselves.
- if (CMAKE_VERSION VERSION_LESS 2.8.11)
- include_directories("${gtest_SOURCE_DIR}/include")
- endif()
-
- # Now simply link against gtest or gtest_main as needed. Eg
- add_executable(example example.cpp)
- target_link_libraries(example gtest_main)
- add_test(NAME example_test COMMAND example)
-
- Note that this approach requires CMake 2.8.2 or later due to
- its use of the `ExternalProject_Add()` command. The above
- technique is discussed in more detail in
- [this separate article](http://crascit.com/2015/07/25/cmake-gtest/)
- which also contains a link to a fully generalized implementation
- of the technique.
-
- ##### Visual Studio Dynamic vs Static Runtimes #####
-
- By default, new Visual Studio projects link the C runtimes dynamically
- but Google Test links them statically.
- This will generate an error that looks something like the following:
- gtest.lib(gtest-all.obj) : error LNK2038: mismatch detected for 'RuntimeLibrary': value 'MTd_StaticDebug' doesn't match value 'MDd_DynamicDebug' in main.obj
-
- Google Test already has a CMake option for this: `gtest_force_shared_crt`
-
- Enabling this option will make gtest link the runtimes dynamically too,
- and match the project in which it is included.
-
- ### Legacy Build Scripts ###
-
- Before settling on CMake, we have been providing hand-maintained build
- projects/scripts for Visual Studio, Xcode, and Autotools. While we
- continue to provide them for convenience, they are not actively
- maintained any more. We highly recommend that you follow the
- instructions in the above sections to integrate Google Test
- with your existing build system.
-
- If you still need to use the legacy build scripts, here's how:
-
- 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 the 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.
-
- On Mac OS X, 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.
-
- If you wish to use the Google Test Xcode project with Xcode 4.x and
- above, you need to either:
-
- * update the SDK configuration options in xcode/Config/General.xconfig.
- Comment options `SDKROOT`, `MACOS_DEPLOYMENT_TARGET`, and `GCC_VERSION`. If
- you choose this route you lose the ability to target earlier versions
- of MacOS X.
- * Install an SDK for an earlier version. This doesn't appear to be
- supported by Apple, but has been reported to work
- (http://stackoverflow.com/questions/5378518).
-
- ### Tweaking Google Test ###
-
- Google Test can be used in diverse environments. The default
- configuration may not work (or may not work well) out of the box in
- some environments. However, you can easily tweak Google Test by
- defining control macros on the compiler command line. Generally,
- these macros are named like `GTEST_XYZ` and you define them to either 1
- or 0 to enable or disable a certain feature.
-
- We list the most frequently used macros below. For a complete list,
- see file [include/gtest/internal/gtest-port.h](include/gtest/internal/gtest-port.h).
-
- ### Choosing a TR1 Tuple Library ###
-
- Some Google Test features require the C++ Technical Report 1 (TR1)
- tuple library, which is not yet 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, 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 want to force Google Test to use its own tuple library, just add
-
- -DGTEST_USE_OWN_TR1_TUPLE=1
-
- to the compiler flags instead.
-
- If you don't want Google Test to use tuple at all, add
-
- -DGTEST_HAS_TR1_TUPLE=0
-
- and all features using tuple will be disabled.
-
- ### Multi-threaded Tests ###
-
- Google Test is thread-safe where the pthread library is available.
- After `#include "gtest/gtest.h"`, you can check the `GTEST_IS_THREADSAFE`
- macro to see whether this is the case (yes if the macro is `#defined` to
- 1, no if it's undefined.).
-
- If Google Test doesn't correctly detect whether pthread is available
- in your environment, you can force it with
-
- -DGTEST_HAS_PTHREAD=1
-
- or
-
- -DGTEST_HAS_PTHREAD=0
-
- When Google Test uses pthread, you may need to add flags to your
- compiler and/or linker to select the pthread library, or you'll get
- link errors. If you use the CMake script or the deprecated Autotools
- script, this is taken care of for you. If you use your own build
- script, you'll need to read your compiler and linker's manual to
- figure out what flags to add.
-
- ### As a Shared Library (DLL) ###
-
- Google Test is compact, so most users can build and link it as a
- static library for the simplicity. You can choose to use Google Test
- as a shared library (known as a DLL on Windows) if you prefer.
-
- To compile *gtest* as a shared library, add
-
- -DGTEST_CREATE_SHARED_LIBRARY=1
-
- to the compiler flags. You'll also need to tell the linker to produce
- a shared library instead - consult your linker's manual for how to do
- it.
-
- To compile your *tests* that use the gtest shared library, add
-
- -DGTEST_LINKED_AS_SHARED_LIBRARY=1
-
- to the compiler flags.
-
- Note: while the above steps aren't technically necessary today when
- using some compilers (e.g. GCC), they may become necessary in the
- future, if we decide to improve the speed of loading the library (see
- <http://gcc.gnu.org/wiki/Visibility> for details). Therefore you are
- recommended to always add the above flags when using Google Test as a
- shared library. Otherwise a future release of Google Test may break
- your build script.
-
- ### Avoiding Macro Name Clashes ###
-
- In C++, macros don't obey namespaces. Therefore two libraries that
- both define a macro of the same name will clash if you `#include` both
- definitions. In case a Google Test macro clashes with another
- library, you can force Google Test to rename its macro to avoid the
- conflict.
-
- Specifically, if both Google Test and some other code define macro
- FOO, you can add
-
- -DGTEST_DONT_DEFINE_FOO=1
-
- to the compiler flags to tell Google Test to change the macro's name
- from `FOO` to `GTEST_FOO`. Currently `FOO` can be `FAIL`, `SUCCEED`,
- or `TEST`. For example, with `-DGTEST_DONT_DEFINE_TEST=1`, you'll
- need to write
-
- GTEST_TEST(SomeTest, DoesThis) { ... }
-
- instead of
-
- TEST(SomeTest, DoesThis) { ... }
-
- in order to define a test.
|