1# Quickstart: Building with CMake
2
3This tutorial aims to get you up and running with GoogleTest using CMake. If
4you're using GoogleTest for the first time or need a refresher, we recommend
5this tutorial as a starting point. If your project uses Bazel, see the
6[Quickstart for Bazel](quickstart-bazel.md) instead.
7
8## Prerequisites
9
10To 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
22See [Supported Platforms](platforms.md) for more information about platforms
23compatible with GoogleTest.
24
25If you don't already have CMake installed, see the
26[CMake installation guide](https://cmake.org/install).
27
28{: .callout .note}
29Note: The terminal commands in this tutorial show a Unix shell prompt, but the
30commands work on the Windows command line as well.
31
32## Set up a project
33
34CMake uses a file named `CMakeLists.txt` to configure the build system for a
35project. You'll use this file to set up your project and declare a dependency on
36GoogleTest.
37
38First, create a directory for your project:
39
40```
41$ mkdir my_project && cd my_project
42```
43
44Next, you'll create the `CMakeLists.txt` file and declare a dependency on
45GoogleTest. There are many ways to express dependencies in the CMake ecosystem;
46in this quickstart, you'll use the
47[`FetchContent` CMake module](https://cmake.org/cmake/help/latest/module/FetchContent.html).
48To do this, in your project directory (`my_project`), create a file named
49`CMakeLists.txt` with the following contents:
50
51```cmake
52cmake_minimum_required(VERSION 3.14)
53project(my_project)
54
55# GoogleTest requires at least C++14
56set(CMAKE_CXX_STANDARD 14)
57set(CMAKE_CXX_STANDARD_REQUIRED ON)
58
59include(FetchContent)
60FetchContent_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
65set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
66FetchContent_MakeAvailable(googletest)
67```
68
69The above configuration declares a dependency on GoogleTest which is downloaded
70from GitHub. In the above example, `03597a01ee50ed33e9dfd640b249b4be3799d395` is
71the Git commit hash of the GoogleTest version to use; we recommend updating the
72hash often to point to the latest version.
73
74For 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
79With GoogleTest declared as a dependency, you can use GoogleTest code within
80your own project.
81
82As an example, create a file named `hello_test.cc` in your `my_project`
83directory with the following contents:
84
85```cpp
86#include <gtest/gtest.h>
87
88// Demonstrate some basic assertions.
89TEST(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
97GoogleTest provides [assertions](primer.md#assertions) that you use to test the
98behavior of your code. The above sample includes the main GoogleTest header file
99and demonstrates some basic assertions.
100
101To build the code, add the following to the end of your `CMakeLists.txt` file:
102
103```cmake
104enable_testing()
105
106add_executable(
107  hello_test
108  hello_test.cc
109)
110target_link_libraries(
111  hello_test
112  GTest::gtest_main
113)
114
115include(GoogleTest)
116gtest_discover_tests(hello_test)
117```
118
119The above configuration enables testing in CMake, declares the C++ test binary
120you want to build (`hello_test`), and links it to GoogleTest (`gtest_main`). The
121last two lines enable CMake's test runner to discover the tests included in the
122binary, using the
123[`GoogleTest` CMake module](https://cmake.org/cmake/help/git-stage/module/GoogleTest.html).
124
125Now 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>
135Scanning dependencies of target gtest
136...
137[100%] Built target gmock_main
138
139<strong>my_project$ cd build && ctest</strong>
140Test project .../my_project/build
141    Start 1: HelloTest.BasicAssertions
1421/1 Test #1: HelloTest.BasicAssertions ........   Passed    0.00 sec
143
144100% tests passed, 0 tests failed out of 1
145
146Total Test time (real) =   0.01 sec
147</pre>
148
149Congratulations! You've successfully built and run a test binary using
150GoogleTest.
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.
158