1 # Quickstart: Building with CMake
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.
10 To complete this tutorial, you'll need:
12 * A compatible operating system (e.g. Linux, macOS, Windows).
13 * A compatible C++ compiler that supports at least C++11.
14 * [CMake](https://cmake.org/) and a compatible build tool for building the
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)
22 See [Supported Platforms](platforms.md) for more information about platforms
23 compatible with GoogleTest.
25 If you don't already have CMake installed, see the
26 [CMake installation guide](https://cmake.org/install).
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.
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
38 First, create a directory for your project:
41 $ mkdir my_project && cd my_project
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:
52 cmake_minimum_required(VERSION 3.14)
55 # GoogleTest requires at least C++11
56 set(CMAKE_CXX_STANDARD 11)
61 URL https://github.com/google/googletest/archive/609281088cfefc76f9d0ce82e1ff6c30cc3591e5.zip
63 # For Windows: Prevent overriding the parent project's compiler/linker settings
64 set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
65 FetchContent_MakeAvailable(googletest)
68 The above configuration declares a dependency on GoogleTest which is downloaded
69 from GitHub. In the above example, `609281088cfefc76f9d0ce82e1ff6c30cc3591e5` is
70 the Git commit hash of the GoogleTest version to use; we recommend updating the
71 hash often to point to the latest version.
73 For more information about how to create `CMakeLists.txt` files, see the
74 [CMake Tutorial](https://cmake.org/cmake/help/latest/guide/tutorial/index.html).
76 ## Create and run a binary
78 With GoogleTest declared as a dependency, you can use GoogleTest code within
81 As an example, create a file named `hello_test.cc` in your `my_project`
82 directory with the following contents:
85 #include <gtest/gtest.h>
87 // Demonstrate some basic assertions.
88 TEST(HelloTest, BasicAssertions) {
89 // Expect two strings not to be equal.
90 EXPECT_STRNE("hello", "world");
96 GoogleTest provides [assertions](primer.md#assertions) that you use to test the
97 behavior of your code. The above sample includes the main GoogleTest header file
98 and demonstrates some basic assertions.
100 To build the code, add the following to the end of your `CMakeLists.txt` file:
109 target_link_libraries(
115 gtest_discover_tests(hello_test)
118 The above configuration enables testing in CMake, declares the C++ test binary
119 you want to build (`hello_test`), and links it to GoogleTest (`gtest_main`). The
120 last two lines enable CMake's test runner to discover the tests included in the
122 [`GoogleTest` CMake module](https://cmake.org/cmake/help/git-stage/module/GoogleTest.html).
124 Now you can build and run your test:
127 <strong>my_project$ cmake -S . -B build</strong>
128 -- The C compiler identification is GNU 10.2.1
129 -- The CXX compiler identification is GNU 10.2.1
131 -- Build files have been written to: .../my_project/build
133 <strong>my_project$ cmake --build build</strong>
134 Scanning dependencies of target gtest
136 [100%] Built target gmock_main
138 <strong>my_project$ cd build && ctest</strong>
139 Test project .../my_project/build
140 Start 1: HelloTest.BasicAssertions
141 1/1 Test #1: HelloTest.BasicAssertions ........ Passed 0.00 sec
143 100% tests passed, 0 tests failed out of 1
145 Total Test time (real) = 0.01 sec
148 Congratulations! You've successfully built and run a test binary using
153 * [Check out the Primer](primer.md) to start learning how to write simple
155 * [See the code samples](samples.md) for more examples showing how to use a
156 variety of GoogleTest features.