docs/quickstart-cmake.md

   1 # Quickstart: Building with CMake
   2
   3 This tutorial aims to get you up and running with GoogleTest using CMake. If
   4 you're using GoogleTest for the first time or need a refresher, we recommend
   5 this tutorial as a starting point. If your project uses Bazel, see the
   6 [Quickstart for Bazel](quickstart-bazel.md) instead.
   7
   8 ## Prerequisites
   9
  10 To complete this tutorial, you'll need:
  11
  12 *   A compatible operating system (e.g. Linux, macOS, Windows).
  13 *   A compatible C++ compiler that supports at least C++14.
  14 *   [CMake](https://cmake.org/) and a compatible build tool for building the
  15     project.
  16     *   Compatible build tools include
  17         [Make](https://www.gnu.org/software/make/),
  18         [Ninja](https://ninja-build.org/), and others - see
  19         [CMake Generators](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html)
  20         for more information.
  21
  22 See [Supported Platforms](platforms.md) for more information about platforms
  23 compatible with GoogleTest.
  24
  25 If you don't already have CMake installed, see the
  26 [CMake installation guide](https://cmake.org/install).
  27
  28 {: .callout .note}
  29 Note: The terminal commands in this tutorial show a Unix shell prompt, but the
  30 commands work on the Windows command line as well.
  31
  32 ## Set up a project
  33
  34 CMake uses a file named `CMakeLists.txt` to configure the build system for a
  35 project. You'll use this file to set up your project and declare a dependency on
  36 GoogleTest.
  37
  38 First, create a directory for your project:
  39
  40 ```
  41 $ mkdir my_project && cd my_project
  42 ```
  43
  44 Next, you'll create the `CMakeLists.txt` file and declare a dependency on
  45 GoogleTest. There are many ways to express dependencies in the CMake ecosystem;
  46 in this quickstart, you'll use the
  47 [`FetchContent` CMake module](https://cmake.org/cmake/help/latest/module/FetchContent.html).
  48 To do this, in your project directory (`my_project`), create a file named
  49 `CMakeLists.txt` with the following contents:
  50
  51 ```cmake
  52 cmake_minimum_required(VERSION 3.14)
  53 project(my_project)
  54
  55 # GoogleTest requires at least C++14
  56 set(CMAKE_CXX_STANDARD 14)
  57 set(CMAKE_CXX_STANDARD_REQUIRED ON)
  58
  59 include(FetchContent)
  60 FetchContent_Declare(
  61   googletest
  62   URL https://github.com/google/googletest/archive/03597a01ee50ed33e9dfd640b249b4be3799d395.zip
  63 )
  64 # For Windows: Prevent overriding the parent project's compiler/linker settings
  65 set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
  66 FetchContent_MakeAvailable(googletest)
  67 ```
  68
  69 The above configuration declares a dependency on GoogleTest which is downloaded
  70 from GitHub. In the above example, `03597a01ee50ed33e9dfd640b249b4be3799d395` is
  71 the Git commit hash of the GoogleTest version to use; we recommend updating the
  72 hash often to point to the latest version.
  73
  74 For more information about how to create `CMakeLists.txt` files, see the
  75 [CMake Tutorial](https://cmake.org/cmake/help/latest/guide/tutorial/index.html).
  76
  77 ## Create and run a binary
  78
  79 With GoogleTest declared as a dependency, you can use GoogleTest code within
  80 your own project.
  81
  82 As an example, create a file named `hello_test.cc` in your `my_project`
  83 directory with the following contents:
  84
  85 ```cpp
  86 #include <gtest/gtest.h>
  87
  88 // Demonstrate some basic assertions.
  89 TEST(HelloTest, BasicAssertions) {
  90   // Expect two strings not to be equal.
  91   EXPECT_STRNE("hello", "world");
  92   // Expect equality.
  93   EXPECT_EQ(7 * 6, 42);
  94 }
  95 ```
  96
  97 GoogleTest provides [assertions](primer.md#assertions) that you use to test the
  98 behavior of your code. The above sample includes the main GoogleTest header file
  99 and demonstrates some basic assertions.
 100
 101 To build the code, add the following to the end of your `CMakeLists.txt` file:
 102
 103 ```cmake
 104 enable_testing()
 105
 106 add_executable(
 107   hello_test
 108   hello_test.cc
 109 )
 110 target_link_libraries(
 111   hello_test
 112   GTest::gtest_main
 113 )
 114
 115 include(GoogleTest)
 116 gtest_discover_tests(hello_test)
 117 ```
 118
 119 The above configuration enables testing in CMake, declares the C++ test binary
 120 you want to build (`hello_test`), and links it to GoogleTest (`gtest_main`). The
 121 last two lines enable CMake's test runner to discover the tests included in the
 122 binary, using the
 123 [`GoogleTest` CMake module](https://cmake.org/cmake/help/git-stage/module/GoogleTest.html).
 124
 125 Now you can build and run your test:
 126
 127 <pre>
 128 <strong>my_project$ cmake -S . -B build</strong>
 129 -- The C compiler identification is GNU 10.2.1
 130 -- The CXX compiler identification is GNU 10.2.1
 131 ...
 132 -- Build files have been written to: .../my_project/build
 133
 134 <strong>my_project$ cmake --build build</strong>
 135 Scanning dependencies of target gtest
 136 ...
 137 [100%] Built target gmock_main
 138
 139 <strong>my_project$ cd build && ctest</strong>
 140 Test project .../my_project/build
 141     Start 1: HelloTest.BasicAssertions
 142 1/1 Test #1: HelloTest.BasicAssertions ........   Passed    0.00 sec
 143
 144 100% tests passed, 0 tests failed out of 1
 145
 146 Total Test time (real) =   0.01 sec
 147 </pre>
 148
 149 Congratulations! You've successfully built and run a test binary using
 150 GoogleTest.
 151
 152 ## Next steps
 153
 154 *   [Check out the Primer](primer.md) to start learning how to write simple
 155     tests.
 156 *   [See the code samples](samples.md) for more examples showing how to use a
 157     variety of GoogleTest features.