# How to Integrate GoogleTest into a CMake Build System: 3 Proven Methods

> Integrate GoogleTest into CMake effortlessly. Discover 3 methods: add_subdirectory, FetchContent, and find_package. Simplify your C++ unit testing workflow today.

- Repository: [Google/googletest](https://github.com/google/googletest)
- Tags: how-to-guide
- Published: 2026-09-01

---

**Add GoogleTest to your CMake project using `add_subdirectory()`, `FetchContent`, or `find_package()`, then link test executables against the `gtest` or `gtest_main` targets to enable C++ unit testing.**

GoogleTest is a widely-used C++ testing framework that ships with first-class CMake support. According to the `google/googletest` source code, the library exposes encapsulated CMake targets defined in [`googletest/CMakeLists.txt`](https://github.com/google/googletest/blob/main/googletest/CMakeLists.txt) that make integration straightforward regardless of whether you vendor the source, fetch it at configure time, or use a system installation. This guide covers the three primary methods to integrate GoogleTest into a CMake build system while referencing the actual implementation details found in the official repository.

## Understanding GoogleTest CMake Targets

The GoogleTest build system defines two primary library targets in [`googletest/CMakeLists.txt`](https://github.com/google/googletest/blob/main/googletest/CMakeLists.txt):

- **`gtest`**: The core testing library built from `src/gtest-all.cc` that contains all assertion macros and test infrastructure.
- **`gtest_main`**: A thin wrapper built from `src/gtest_main.cc` that provides a default `main()` function, allowing test binaries to link without defining their own entry point.

Both targets are constructed using the `cxx_library()` macro defined in `cmake/internal_utils.cmake`. The top-level [`CMakeLists.txt`](https://github.com/google/googletest/blob/main/CMakeLists.txt) (located in the repository root) orchestrates the build, enforces C++17 (required for version 1.18.x and later), and handles optional features like hermetic builds via `cmake/hermetic_build.cmake`.

If you need mocking capabilities, the [`googlemock/CMakeLists.txt`](https://github.com/google/googletest/blob/main/googlemock/CMakeLists.txt) file defines the `gmock` and `gmock_main` targets, which automatically pull in the underlying GoogleTest libraries.

## Method 1: Vendoring with add_subdirectory

The simplest approach for projects that vendor dependencies is to include the GoogleTest source tree directly. This method exposes the `gtest` and `gtest_main` targets immediately to your build.

```cmake
cmake_minimum_required(VERSION 3.16)
project(MyProject LANGUAGES CXX)

# Pull GoogleTest into the build tree

add_subdirectory(external/googletest)   # Path to cloned repository

# Your production library

add_library(my_lib src/my_lib.cpp)

# Test executable linking against gtest_main

add_executable(my_lib_test test/my_lib_test.cpp)
target_link_libraries(my_lib_test PRIVATE my_lib gtest_main)

# Enable CTest integration

enable_testing()
add_test(NAME MyLibTest COMMAND my_lib_test)

```

When `add_subdirectory()` processes the top-level [`CMakeLists.txt`](https://github.com/google/googletest/blob/main/CMakeLists.txt), it invokes the library definitions in [`googletest/CMakeLists.txt`](https://github.com/google/googletest/blob/main/googletest/CMakeLists.txt), making the targets available for linking. Set `BUILD_GMOCK=ON` before the `add_subdirectory()` call if you require mock support.

## Method 2: FetchContent for Automatic Downloads

For projects that prefer automatic dependency management, CMake's `FetchContent` module downloads and integrates GoogleTest at configure time without manual cloning.

```cmake
include(FetchContent)

FetchContent_Declare(
  googletest
  URL https://github.com/google/googletest/archive/refs/tags/v1.18.0.tar.gz
)

# For Windows: avoid overriding parent project's runtime library settings

set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)

FetchContent_MakeAvailable(googletest)

add_executable(sample_test test/sample_test.cpp)
target_link_libraries(sample_test PRIVATE gtest_main)

```

The `FetchContent_MakeAvailable` command executes the top-level GoogleTest distribution script, which handles the `googletest` subdirectory inclusion internally. This approach respects all standard GoogleTest options, including `INSTALL_GTEST` and `BUILD_GMOCK`.

## Method 3: Finding an Installed GoogleTest

When GoogleTest is installed system-wide or to a custom prefix, use CMake's package configuration system. The installation process generates `GTestConfig.cmake` and `GTestConfigVersion.cmake` via `CMakePackageConfigHelpers` (as implemented in [`googletest/CMakeLists.txt`](https://github.com/google/googletest/blob/main/googletest/CMakeLists.txt)), enabling discovery through `find_package()`.

```cmake
cmake_minimum_required(VERSION 3.16)
project(Consumer LANGUAGES CXX)

find_package(GTest REQUIRED)

add_executable(consumer_test test/consumer_test.cpp)
target_link_libraries(consumer_test PRIVATE GTest::gtest_main)

```

The `find_package` call locates the installed package configuration files under `${CMAKE_INSTALL_LIBDIR}/cmake/GTest`. Note that when using installed packages, targets are prefixed with the `GTest::` namespace (e.g., `GTest::gtest_main` rather than just `gtest_main`).

## Key Configuration Options and Build Details

Several CMake variables control the GoogleTest build behavior:

- **`BUILD_GMOCK`**: When enabled, builds the GoogleMock libraries (which inherently include GoogleTest).
- **`gtest_force_shared_crt`**: On Windows, forces the use of shared runtime libraries to avoid linker conflicts with parent projects.
- **`INSTALL_GTEST`**: Controls whether `install_project()` is invoked to generate and install `GTestConfig.cmake` for downstream consumption.
- **C++ Standard**: The top-level [`CMakeLists.txt`](https://github.com/google/googletest/blob/main/CMakeLists.txt) enforces C++17 for version 1.18.x and later branches via `CMAKE_CXX_STANDARD` requirements.

The library definition in [`googletest/CMakeLists.txt`](https://github.com/google/googletest/blob/main/googletest/CMakeLists.txt) uses `target_include_directories()` to expose `${gtest_SOURCE_DIR}/include`, ensuring that consumers automatically receive the correct header paths without manual `include_directories()` calls.

## Summary

- **GoogleTest exposes two primary targets**: `gtest` (core library) and `gtest_main` (includes default `main()`), both defined in [`googletest/CMakeLists.txt`](https://github.com/google/googletest/blob/main/googletest/CMakeLists.txt).
- **Three integration methods** are officially supported: `add_subdirectory()` for vendoring, `FetchContent` for automatic downloads, and `find_package()` for system installations.
- **Link `gtest_main`** to avoid writing boilerplate `main()` functions, or link `gtest` if you provide custom initialization logic.
- **Enable `INSTALL_GTEST`** during the build to generate CMake package configuration files, allowing other projects to locate the library via `find_package(GTest)`.

## Frequently Asked Questions

### What is the difference between linking gtest versus gtest_main?

The `gtest` target contains only the core testing framework (assertions, test registration, and event listeners), while `gtest_main` additionally provides a standard `main()` function implementation. Link `gtest_main` for typical unit test executables, or link `gtest` if your project requires a custom `main()` function for specialized test initialization or environment setup.

### How do I enable GoogleMock support during CMake integration?

Set the option `BUILD_GMOCK=ON` before adding GoogleTest to your project via `add_subdirectory()` or `FetchContent_MakeAvailable()`. This builds the `gmock` and `gmock_main` targets from [`googlemock/CMakeLists.txt`](https://github.com/google/googletest/blob/main/googlemock/CMakeLists.txt), which automatically link against the underlying GoogleTest libraries.

### Why does CMake fail with errors about C++17 requirements?

GoogleTest version 1.18.x and later require C++17 or newer, as enforced by the top-level [`CMakeLists.txt`](https://github.com/google/googletest/blob/main/CMakeLists.txt). Ensure your project sets `CMAKE_CXX_STANDARD` to 17 or higher, or that your compiler defaults to at least C++17, before configuring the GoogleTest build.

### Can I export GoogleTest for use in multiple projects without rebuilding?

Yes. Enable `INSTALL_GTEST=ON` in your GoogleTest build configuration, then run `cmake --install` to deploy the libraries and headers. This installs `GTestConfig.cmake` to `${CMAKE_INSTALL_LIBDIR}/cmake/GTest`, allowing unlimited downstream projects to locate and link against a single GoogleTest installation using `find_package(GTest REQUIRED)`.