Integrating Third-Party Dependencies: FetchContent vs. ExternalProject_Add

The Dependency Integration Problem

When adding third-party libraries to a CMake project, the primary challenge is deciding when the dependency should be configured and built. Choosing the wrong mechanism can lead to broken IDE integrations, bloated configuration times, or build failures due to incompatible toolchains. The core decision is whether the dependency should be treated as part of your own project's source tree or as an isolated external entity.

Comparison of Integration Mechanisms

Feature	FetchContent	ExternalProject_Add
Execution Phase	Configuration time (cmake -S . -B build)	Build time (cmake --build build)
Target Visibility	Targets are native; visible to IDEs	Targets are opaque; hidden from IDEs
Toolchain	Shares parent project's compiler/flags	Can use a completely separate toolchain
Build System	Must be CMake-compatible	Any (Make, Autotools, Ninja, etc.)
Configuration Speed	Slower (adds to configure step)	Faster (deferred to build step)

Engineering Trade-offs

FetchContent: The Integrated Approach

FetchContent downloads and adds the dependency to the current CMake session. This allows you to use target_link_libraries() directly with the dependency's targets. It is the ideal choice for "header-only" libraries or CMake-based projects that are compatible with your current compiler settings. The main risk is configuration latency; every time you clear your build directory, CMake must re-download and re-configure the dependency unless a persistent cache is configured.

ExternalProject_Add: The Isolated Approach

ExternalProject_Add treats the dependency as a separate project. It runs its own configure, build, and install steps during the build phase. This provides strong isolation, making it the only viable choice for libraries using non-CMake build systems or those requiring a different version of CMake. The trade-off is a loss of IDE visibility; because the targets aren't defined until the build starts, your IDE cannot provide autocomplete or jump-to-definition for the external library's source code.

Implementation: FetchContent

Use this pattern for CMake-compatible libraries like GoogleTest. This example assumes CMake 3.14+ for FetchContent_MakeAvailable.

cmake_minimum_required(VERSION 3.14)
project(FetchDemo LANGUAGES CXX)

include(FetchContent)

# Declare the dependency
FetchContent_Declare(
  googletest
  GIT_REPOSITORY https://github.com/google/googletest.git
  GIT_TAG release-1.14.0
)

# Download and add to the project
FetchContent_MakeAvailable(googletest)

add_executable(my_test test.cpp)
# Link directly to the target provided by the dependency
target_link_libraries(my_test PRIVATE GTest::gtest_main)

Verification:

1. Run cmake -S . -B build. Observe the download logs during the configuration phase.
2. Run cmake --build build. The gtest targets will compile as part of your project.
3. Check that the target GTest::gtest_main is recognized by the linker.

Implementation: ExternalProject_Add

Use this pattern for projects that must remain isolated or use different build tools. Note that you must manually specify the paths to the resulting artifacts.

cmake_minimum_required(VERSION 3.10)
project(ExternalDemo LANGUAGES CXX)

include(ExternalProject)

ExternalProject_Add(
  googletest_ext
  GIT_REPOSITORY https://github.com/google/googletest.git
  GIT_TAG release-1.14.0
  PREFIX ${CMAKE_BINARY_DIR}/googletest
  INSTALL_COMMAND ""
)

add_executable(my_test test.cpp)

# Manually define the paths since targets aren't available at config time
target_include_directories(my_test PRIVATE ${CMAKE_BINARY_DIR}/googletest/src/googletest/include)
target_link_libraries(my_test PRIVATE ${CMAKE_BINARY_DIR}/googletest/lib/libgtest.a)

# Ensure the external project is built before the executable
add_dependencies(my_test googletest_ext)

Verification:

1. Run cmake -S . -B build. The configuration should finish almost instantly without downloading.
2. Run cmake --build build. Observe the googletest_ext step triggering the download and build.
3. Verify the binary exists at the specified ${CMAKE_BINARY_DIR} path.

Limitations and Practical Checks

Network Dependency: Both methods require internet access. To avoid repeated downloads in FetchContent, set FETCHCONTENT_BASE_DIR to a directory outside your build folder.

Toolchain Conflicts: If FetchContent fails with compiler errors related to flags or versions, it is a signal that the dependency is incompatible with your project's global settings. Switch to ExternalProject_Add to isolate the build environment.

Rollback: To remove these dependencies, delete the FetchContent_Declare or ExternalProject_Add blocks and remove the corresponding target_link_libraries entries. Delete the build directory to clear cached artifacts.