Fetching External Dependencies

Let's update our main.cpp to use spdlog, replacing our std::cout usage with a call to spdlog::info():

1#include <iostream>
2#include <greeter/Greeter.h>
3#include <spdlog/spdlog.h> // We want to use spdlog 
4
5int main() {
6  spdlog::info(get_greeting()); // Use the logger 
7  return 0;
8}

Now, how do we link GreeterApp to spdlog? The spdlog library provides a modern CMake target called spdlog::spdlog. The natural thing to do would be to simply link against it:

1cmake_minimum_required(VERSION 3.16)
2add_executable(GreeterApp src/main.cpp)
3
4include(ExternalProject)
5
6ExternalProject_Add(spdlog_external
7  GIT_REPOSITORY https://github.com/gabime/spdlog.git
8  GIT_TAG v1.15.3
9  CMAKE_ARGS
10    -DCMAKE_INSTALL_PREFIX=${CMAKE_BINARY_DIR}/spdlog_install
11)
12
13target_link_libraries(GreeterApp
14  GreeterLib
15  spdlog::spdlog
16)

Alas, this won't work:

1CMake Error at app/CMakeLists.txt:13 (target_link_libraries):
2  Target "GreeterApp" links to:
3
4    spdlog::spdlog
5
6  but the target was not found.

This error exposes the fundamental limitation of ExternalProject_Add(). The spdlog_external target only downloads and builds spdlog when we run cmake --build . (the build step). But target_link_libraries() is evaluated when we run cmake .. (the configure step).

At configure time, the spdlog::spdlog target simply does not exist yet. CMake has no knowledge of it, so it can't create the link, view the target's properties, or perform any similar action that might be useful for our build script.

The Old Workarounds

Before FetchContent existed, developers used complex and brittle workarounds for this, broadly involving referencing files and paths that may not exist yet (in the configure step) but we think will in the future (in the build step, after it has downloaded and built the package).

The techniques varied on a case-by-case basis depending on how each dependency worked, but the simplest cases involve:

1. Manually addding the include directory using the hardcoded path where ExternalProject_Add() will build spdlog (eg ${CMAKE_BINARY_DIR}/spdlog_install/include).
2. Manually adding the path to the compiled library file (eg ${CMAKE_BINARY_DIR}/spdlog_install/lib/libspdlog.a).
3. Manually intervening in the dependency graph construction using commands like add_dependencies() to ensure the spdlog was built before the GreeterApp target that requires it. We introduce add_dependencies() and other practical use cases for it in the next chapter.

A working implementation of this approach for spdlog is provided below for reference but, where possible, we'd rather move to the more modern, target-based dependency management.

1cmake_minimum_required(VERSION 3.16)
2include(ExternalProject)
3add_executable(GreeterApp src/main.cpp)
4
5# Set where spdlog will be installed in our build directory
6set(SPDLOG_INSTALL_DIR ${CMAKE_BINARY_DIR}/spdlog_install)
7
8ExternalProject_Add(spdlog_external
9  GIT_REPOSITORY https://github.com/gabime/spdlog.git
10  GIT_TAG v1.15.3
11  # Updated to use our new variable
12  CMAKE_ARGS
13    -DCMAKE_INSTALL_PREFIX=${SPDLOG_INSTALL_DIR}
14)
15
16# Create an IMPORTED proxy target to represent spdlog
17add_library(spdlog_proxy STATIC IMPORTED GLOBAL)
18
19# Construct the expected library file name portably
20set(SPDLOG_LIB_FILENAME 
21  # This is "lib" on Linux, "" on Windows
22  "${CMAKE_STATIC_LIBRARY_PREFIX}"
23  "spdlog"
24  # This is ".a" on Linux, ".lib" on Windows
25  "${CMAKE_STATIC_LIBRARY_SUFFIX}"
26)
27
28# Set paths we assume will exist after spdlog is built
29set_target_properties(spdlog_proxy PROPERTIES
30  IMPORTED_LOCATION
31  "${SPDLOG_INSTALL_DIR}/lib/${SPDLOG_LIB_FILENAME}"
32  INTERFACE_INCLUDE_DIRECTORIES
33  "${SPDLOG_INSTALL_DIR}/include"
34)
35
36# Manually enforce the build order
37add_dependencies(GreeterApp spdlog_external)
38
39target_link_libraries(GreeterApp
40  GreeterLib
41  # Link against our proxy, not the real target
42  spdlog_proxy
43)

This is a significant amount of complex, non-portable boilerplate.

Most notably, it requires us know internal details about the library, such as its installation layout (/lib, /include). If spdlog ever changes something we rely on, this script would break.

This pattern is a maintenance nightmare at scale, and it's the primary problem that FetchContent() was designed to solve.

The CMake developers recognized this problem and created the FetchContent() module. FetchContent() is a modern wrapper around ExternalProject_Add() designed to solve the configure-time visibility problem.

It works by splitting the process into distinct steps, and it performs the download (the "population") step during configuration. This allows it to call add_subdirectory() behind the scenes to load the CMakeLists.txt of what we just downloaded, making all of the dependency's targets available to the rest of your CMakeLists.txt.

The FetchContent() Workflow

Let's refactor our app/CMakeLists.txt to use the modern FetchContent() pattern.

1cmake_minimum_required(VERSION 3.16)
2add_executable(GreeterApp src/main.cpp)
3
4# Step 1: Replace ExternalProject with FetchContent
5include(ExternalProject)
6include(FetchContent) 
7
8# Step 2: Declare the dependency
9FetchContent_Declare(spdlog 
10  GIT_REPOSITORY https://github.com/gabime/spdlog.git 
11  GIT_TAG v1.15.3 
12) 
13
14# Step 3: Make the content available
15FetchContent_MakeAvailable(spdlog) 
16
17# No changes needed
18target_link_libraries(GreeterApp
19  GreeterLib
20  spdlog::spdlog
21)

Let's walk through this new, cleaner script:

1. include(FetchContent): We include the module that provides the new commands.
2. FetchContent_Declare(spdlog ...): This step registers our dependency. We give it a name (spdlog) and provide the same source code details (GIT_REPOSITORY, GIT_TAG) as before. This command doesn't actually download anything yet; it just records the information.
3. FetchContent_MakeAvailable(spdlog): This command checks if the spdlog content has already been populated. If not, it downloads it into the build directory. Then, behind the scenes, it calls add_subdirectory() on the the directory it just downloaded.

Because add_subdirectory() is called, CMake immediately processes spdlog's own CMakeLists.txt file. This creates the spdlog::spdlog target, making it visible and available right away.

Now, when our script reaches the target_link_libraries() command, spdlog::spdlog is a known target. CMake can create the link, and all of spdlog's usage requirements (like its public include directories) are automatically propagated to GreeterApp.

If we configure and build this version, everything should work seamlessly.

1cmake ..

1cmake --build .

If we run our new GreeterApp (or GreeterApp.exe) we should now see our logs augmented with a timestamp and verbosity indicator (info, in this example):

1./app/GreeterApp

1[2025-08-22 10:30:00.000] [info] Hello from the modular greeter library!

Many more examples of what spdlog can do, as well as links to documentation, are available on their GitHub page.

We now have two primary ways to handle external dependencies: finding them on the system with find_package(), or fetching them from source. Each approach has trade-offs.

We have now covered two tools for managing dependencies, each with its own strengths:

• find_package() is fast and uses system-native libraries, but requires the user to pre-install them.
• ExternalProject_Add() or FetchContent() is reproducible and requires no setup from the user, but can be slow as it compiles from source.

Can we get the best of both worlds? A very common and robust pattern in modern CMake is to try to find the package first, and only fetch it if it's not found.

This gives users the option to use a fast, pre-compiled system library if they have one, while guaranteeing that the build will still work for anyone by falling back to fetching from source.

A Practical Example

Let's implement this "find-or-fetch" pattern for our spdlog dependency. We'll modify app/CMakeLists.txt to incorporate this logic.

The key is to use find_package() without the REQUIRED keyword, which prevents it from halting the build on failure. We can then check the spdlog_FOUND variable it sets to decide our next move.

1cmake_minimum_required(VERSION 3.16)
2include(FetchContent)
3
4# Step 1: Try to find an existing spdlog installation.
5# The QUIET keyword prevents it from outputting a warning
6find_package(spdlog 1.1 QUIET) 
7
8# Step 2: If it wasn't found, fetch it from source.
9if(spdlog_FOUND) 
10  message(STATUS "Found spdlog version ${spdlog_VERSION}") 
11else() 
12  message(STATUS "spdlog not found. Fetching from source") 
13  FetchContent_Declare(spdlog 
14    GIT_REPOSITORY https://github.com/gabime/spdlog.git 
15    GIT_TAG v1.15.3 
16  ) 
17  FetchContent_MakeAvailable(spdlog) 
18endif() 
19
20add_executable(GreeterApp src/main.cpp)
21
22target_link_libraries(GreeterApp
23  GreeterLib
24  # This works regardless of where spdlog came from
25  spdlog::spdlog
26)

Notice that the target_link_libraries() call is completely unchanged and sits outside the conditional logic. This is the beauty of target-based dependency management.

The consumer, GreeterApp, doesn't care how the spdlog::spdlog target was created - whether it was an IMPORTED target from find_package or a STATIC/SHARED target from FetchContent. It just needs the target to exist, and this script almost guarantees that it will.

Why Are The Versions Different?

Note that the versions we specify in find_package() and in FetchContent_Declare() need not be the same. Again, this is because the version we set has different implications between these two commands.

• In the find case, we specify the minimum version we can work with - e.g. find_package(spdlog 1.1).
• If find fails and we must fetch, we can choose the exact version we want to ship with. This is often newer than the minimum - eg v1.15.3.

If the user or project already has a compatible library installed, you don't want to force-upgrade it unnecessarily; that can cause conflicts.

But if we're fetching anyway, there's no risk of breaking other projects, so we can pull in a newer, stable version with the latest bugfixes and improvements.

In this lesson, we've learned how to create self-sufficient projects that automatically fetching their dependencies from source.

• ExternalProject_Add(): The classic, powerful tool that downloads and builds dependencies at build time. Its main drawback is that its targets are not visible at configure time, making integration complex.
• FetchContent(): The modern, preferred tool that downloads dependencies at configure time. By using add_subdirectory(), it makes the dependency's targets immediately available, allowing for seamless integration with target_link_libraries().
• The Workflow: Use FetchContent_Declare() to register a dependency and FetchContent_MakeAvailable() to download and integrate it.
• Trade-offs: Fetching dependencies provides excellent reproducibility and a simpler user experience but results in longer build times compared to using pre-compiled system libraries with find_package().