| 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++11. |
| 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++11 |
| 56 |
set(CMAKE_CXX_STANDARD 11) |
| 57 |
|
| 58 |
include(FetchContent) |
| 59 |
FetchContent_Declare( |
| 60 |
googletest |
| 61 |
URL https://github.com/google/googletest/archive/609281088cfefc76f9d0ce82e1ff6c30cc3591e5.zip |
| 62 |
) |
| 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) |
| 66 |
``` |
| 67 |
|
| 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. |
| 72 |
|
| 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). |
| 75 |
|
| 76 |
## Create and run a binary |
| 77 |
|
| 78 |
With GoogleTest declared as a dependency, you can use GoogleTest code within |
| 79 |
your own project. |
| 80 |
|
| 81 |
As an example, create a file named `hello_test.cc` in your `my_project` |
| 82 |
directory with the following contents: |
| 83 |
|
| 84 |
```cpp |
| 85 |
#include <gtest/gtest.h> |
| 86 |
|
| 87 |
// Demonstrate some basic assertions. |
| 88 |
TEST(HelloTest, BasicAssertions) { |
| 89 |
// Expect two strings not to be equal. |
| 90 |
EXPECT_STRNE("hello", "world"); |
| 91 |
// Expect equality. |
| 92 |
EXPECT_EQ(7 * 6, 42); |
| 93 |
} |
| 94 |
``` |
| 95 |
|
| 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. |
| 99 |
|
| 100 |
To build the code, add the following to the end of your `CMakeLists.txt` file: |
| 101 |
|
| 102 |
```cmake |
| 103 |
enable_testing() |
| 104 |
|
| 105 |
add_executable( |
| 106 |
hello_test |
| 107 |
hello_test.cc |
| 108 |
) |
| 109 |
target_link_libraries( |
| 110 |
hello_test |
| 111 |
gtest_main |
| 112 |
) |
| 113 |
|
| 114 |
include(GoogleTest) |
| 115 |
gtest_discover_tests(hello_test) |
| 116 |
``` |
| 117 |
|
| 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 |
| 121 |
binary, using the |
| 122 |
[`GoogleTest` CMake module](https://cmake.org/cmake/help/git-stage/module/GoogleTest.html). |
| 123 |
|
| 124 |
Now you can build and run your test: |
| 125 |
|
| 126 |
<pre> |
| 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 |
| 130 |
... |
| 131 |
-- Build files have been written to: .../my_project/build |
| 132 |
|
| 133 |
<strong>my_project$ cmake --build build</strong> |
| 134 |
Scanning dependencies of target gtest |
| 135 |
... |
| 136 |
[100%] Built target gmock_main |
| 137 |
|
| 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 |
| 142 |
|
| 143 |
100% tests passed, 0 tests failed out of 1 |
| 144 |
|
| 145 |
Total Test time (real) = 0.01 sec |
| 146 |
</pre> |
| 147 |
|
| 148 |
Congratulations! You've successfully built and run a test binary using |
| 149 |
GoogleTest. |
| 150 |
|
| 151 |
## Next steps |
| 152 |
|
| 153 |
* [Check out the Primer](primer.md) to start learning how to write simple |
| 154 |
tests. |
| 155 |
* [See the code samples](samples.md) for more examples showing how to use a |
| 156 |
variety of GoogleTest features. |