Skip to content

Commit d4e3b8c

Browse files
Abseil Teamdinord
Abseil Team
authored and
dinord
committed
Googletest export
Add CMake quickstart PiperOrigin-RevId: 364437779
1 parent 32ad3c8 commit d4e3b8c

File tree

2 files changed

+158
-0
lines changed

2 files changed

+158
-0
lines changed

‎docs/_data/navigation.yml

+2
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ nav:
55
url: "/platforms.html"
66
- title: "Quickstart: Bazel"
77
url: "/quickstart-bazel.html"
8+
- title: "Quickstart: CMake"
9+
url: "/quickstart-cmake.html"
810
- section: "Guides"
911
items:
1012
- title: "GoogleTest Primer"

‎docs/quickstart-cmake.md

+156
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
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.

0 commit comments

Comments
 (0)