Quickstart: Building with CMake

This tutorial aims to get you up and running with GoogleTest using CMake. If
you’re using GoogleTest for the first time or need a refresher, we recommend
this tutorial as a starting point. If your project uses Bazel, see the
Quickstart for Bazel instead.

Prerequisites

To complete this tutorial, you’ll need:

  • A compatible operating system (e.g. Linux, macOS, Windows).
  • A compatible C++ compiler that supports at least C++11.

  • CMake and a compatible build tool for building the
    project.

See Supported Platforms for more information about platforms
compatible with GoogleTest.

If you don’t already have CMake installed, see the
CMake installation guide.

{: .callout .note}
Note: The terminal commands in this tutorial show a Unix shell prompt, but the
commands work on the Windows command line as well.

Set up a project

CMake uses a file named CMakeLists.txt to configure the build system for a
project. You’ll use this file to set up your project and declare a dependency on
GoogleTest.

First, create a directory for your project:

  1. $ mkdir my_project && cd my_project

Next, you’ll create the CMakeLists.txt file and declare a dependency on
GoogleTest. There are many ways to express dependencies in the CMake ecosystem;
in this quickstart, you’ll use the
FetchContent CMake module.
To do this, in your project directory (my_project), create a file named
CMakeLists.txt with the following contents:

  1. cmake_minimum_required(VERSION 3.14)
  2. project(my_project)
  4. # GoogleTest requires at least C++11
  5. set(CMAKE_CXX_STANDARD 11)
  7. include(FetchContent)
  8. FetchContent_Declare(
  9.   googletest
  10.   URL https://github.com/google/googletest/archive/609281088cfefc76f9d0ce82e1ff6c30cc3591e5.zip
  11. )
  12. # For Windows: Prevent overriding the parent project's compiler/linker settings
  13. set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
  14. FetchContent_MakeAvailable(googletest)

The above configuration declares a dependency on GoogleTest which is downloaded
from GitHub. In the above example, 609281088cfefc76f9d0ce82e1ff6c30cc3591e5 is
the Git commit hash of the GoogleTest version to use; we recommend updating the
hash often to point to the latest version.

For more information about how to create CMakeLists.txt files, see the
CMake Tutorial.

Create and run a binary

With GoogleTest declared as a dependency, you can use GoogleTest code within
your own project.

As an example, create a file named hello_test.cc in your my_project
directory with the following contents:

  1. #include <gtest/gtest.h>
  3. // Demonstrate some basic assertions.
  4. TEST(HelloTest, BasicAssertions) {
  5.   // Expect two strings not to be equal.
  6.   EXPECT_STRNE("hello", "world");
  7.   // Expect equality.
  8.   EXPECT_EQ(7 * 6, 42);
  9. }

GoogleTest provides assertions that you use to test the
behavior of your code. The above sample includes the main GoogleTest header file
and demonstrates some basic assertions.

To build the code, add the following to the end of your CMakeLists.txt file:

  1. enable_testing()
  3. add_executable(
  4.   hello_test
  5.   hello_test.cc
  6. )
  7. target_link_libraries(
  8.   hello_test
  9.   gtest_main
  10. )
  12. include(GoogleTest)
  13. gtest_discover_tests(hello_test)

The above configuration enables testing in CMake, declares the C++ test binary
you want to build (hello_test), and links it to GoogleTest (gtest_main). The
last two lines enable CMake’s test runner to discover the tests included in the
binary, using the
GoogleTest CMake module.

Now you can build and run your test:

my_project$ cmake -S . -B buildmy_project$ cmake —build buildmy_project$ cd build && ctest Congratulations! You’ve successfully built and run a test binary using
GoogleTest.

Next steps