Using CMake ExternalProject_Add to Fetch and Build GoogleTest Automatically

Desired outcome

Automatically download, build, and link GoogleTest (or any other external library) as part of your project’s build tree so that a test target can be compiled and run without manual dependency installation.

Prerequisites

• CMake 3.0 or newer (ExternalProject_Add is available from this version)
• A working C++ compiler toolchain
• Internet access for cloning the GoogleTest repository
• A basic CMakeLists.txt that defines at least one executable or library target

Procedure

1. Include the ExternalProject module

   # At the top of your CMakeLists.txt, after cmake_minimum_required
   include(ExternalProject)

2. Declare the external project

   Place this call where you want the dependency to be defined (typically after your own targets). Adjust GIT_TAG to a specific release or commit as needed.

   ExternalProject_Add_googletest
     PREFIX               ${CMAKE_BINARY_DIR}/googletest
     GIT_REPOSITORY       https://github.com/google/googletest.git
     GIT_TAG              release-1.14.0   # example tag
     CONFIGURE_COMMAND    ""  # we will use the default CMake build of googletest
     BUILD_COMMAND        ""
     INSTALL_COMMAND      ""
     TEST_COMMAND         ""

   This tells CMake to create a subdirectory ${CMAKE_BINARY_DIR}/googletest where the source will be cloned and built.

3. Retrieve the install locations

   After the external project is built, query its properties to find the include directory and the compiled library.

   ExternalProject_Get_Property(googletest source_dir binary_dir)
   # GoogleTest installs headers under googletest/src/googletest/include
   # and the library under googletest/lib (or lib64 on some systems)
   set(GTEST_INCLUDE_DIR ${source_dir}/googletest/include)
   set(GTEST_LIBRARY   ${binary_dir}/libgtest.a)

   If you prefer the installed location, you can add an INSTALL_COMMAND step and query INSTALL_DIR instead.

4. Create your test executable

   add_executable(my_test test_main.cpp)
   target_include_directories(my_test PRIVATE ${GTEST_INCLUDE_DIR})
   target_link_libraries(my_test PRIVATE ${GTEST_LIBRARY} pthread)

5. Ensure the external project builds first

   Because ExternalProject_Add runs at build time, you must add an explicit dependency so that CMake waits for googletest to finish before compiling my_test.

   add_dependencies(my_test googletest)

Expected checks

• After running cmake -S . -B build and cmake --build build, verify that the directory build/googletest contains a src subdirectory with the googletest source and a build subdirectory (often googletest-build) containing libgtest.a.
• Confirm that the variables GTEST_INCLUDE_DIR and GTEST_LIBRARY resolve to existing files on disk (e.g., file(${GTEST_INCLUDE_DIR}/gtest/gtest.h) returns true).
• Build the test target and run it: ./build/my_test should execute and report test results.

Recovery options and limitations

• Network failures: If the git clone fails, check your internet connection, firewall, or proxy settings. The logs are available in build/googletest/src (the git output) and build/googletest-*/ for build steps.
• Build errors: Examine build/googletest-*/ for compiler output. Common issues include missing dependencies (e.g., make or a compatible compiler) or using an incompatible GIT_TAG.
• Build time increase: Because googletest is compiled as part of your project, incremental builds will rebuild it if its source changes. Consider using a version control submodule or a binary cache if rebuilds are too costly.
• Configuration‑time discovery: ExternalProject_Add does not make headers or libraries available during the initial cmake configuration step. If you need to reference the external library in configure_file or similar, use FetchContent (available from CMake 3.11) instead.