In CMake, how do FetchContent_Declare and FetchContent_MakeAvailable bring in a dependency, and how can an installed copy win instead?
answer
- declare first, populate later
- configure time, then add_subdirectory
- first declaration wins
- FIND_PACKAGE_ARGS and OVERRIDE_FIND_PACKAGE
basics
~10 sFetchContent_Declare records where a dependency's source comes from; FetchContent_MakeAvailable downloads it at configure time and adds it with add_subdirectory. With FIND_PACKAGE_ARGS it first tries find_package and fetches only when that fails.
solid answer
~40 s`FetchContent_Declare(hdr URL ... URL_HASH SHA256=...)` only records details, and the first declaration of a name wins, so a top-level project can override what a nested project declares. `FetchContent_MakeAvailable(hdr)` populates it during configure, into `_deps/hdr-src` by default, and calls `add_subdirectory` when the source has a `CMakeLists.txt`, so its targets join your build. Since CMake 3.24, `FIND_PACKAGE_ARGS` makes `MakeAvailable` call `find_package(hdr <args>)` first and fetch only if that fails; `FETCHCONTENT_TRY_FIND_PACKAGE_MODE` (`OPT_IN` by default, `ALWAYS`, `NEVER`) lets the user change that. `OVERRIDE_FIND_PACKAGE` works the other way: later `find_package(hdr)` calls are satisfied by the fetched copy. `ExternalProject_Add` differs in kind: it builds a separate project at build time, so its targets are not available at configure time.
code
cmake · 13 linescmake_minimum_required(VERSION 3.25)
project(viewer CXX)
include(FetchContent)
FetchContent_Declare(hdr
URL https://example.com/hdr-2.1.tar.gz
URL_HASH SHA256=<hash of the archive>
FIND_PACKAGE_ARGS 2.0 CONFIG # try an installed hdr >= 2.0 first
)
FetchContent_MakeAvailable(hdr)
add_executable(viewer main.cpp)
target_link_libraries(viewer PRIVATE hdr::hdr)go deeper
Recall the two-step pattern, Declare then MakeAvailable, and that the fetched project's targets can be linked right after MakeAvailable returns.
Explain configure-time population, first declaration wins, and how FIND_PACKAGE_ARGS and FETCHCONTENT_TRY_FIND_PACKAGE_MODE let an installed package satisfy the dependency first.
Pin content by commit or hash, use SYSTEM and EXCLUDE_FROM_ALL so a dependency's warnings and targets stay out of your way, and pick ExternalProject only when isolation is the point.
Weigh the configure-time download and from-source build cost of FetchContent against prebuilt packages, and decide which dependencies a team may fetch at all.
## Two commands, two phases The `FetchContent` module (since CMake 3.11, `include(FetchContent)`) brings a dependency's **source** into the build while CMake is configuring. It splits the job in two: 1. **`FetchContent_Declare(<name> <options>...)`** records how to get the content: `URL` with `URL_HASH`, `GIT_REPOSITORY` with `GIT_TAG`, and the other download, update and patch options `ExternalProject_Add` understands. It downloads nothing. 2. **`FetchContent_MakeAvailable(<name>...)`** makes each named dependency available by the time it returns: it populates the source (by default under `<build>/_deps/<name>-src`), sets `<lowercasename>_SOURCE_DIR` and `<lowercasename>_BINARY_DIR`, and, if the populated directory has a `CMakeLists.txt`, calls `add_subdirectory` on it. Because the dependency is added as a subdirectory, its targets are ordinary targets of your build. A header-only library declared this way can be linked as soon as `MakeAvailable` returns: ```cmake include(FetchContent) FetchContent_Declare(hdr URL https://example.com/hdr-2.1.tar.gz URL_HASH SHA256=<hash of the archive> ) FetchContent_MakeAvailable(hdr) target_link_libraries(app PRIVATE hdr::hdr) ``` ## First declaration wins If several projects in one build declare the same name, **the first `FetchContent_Declare` call is kept and later ones are ignored**, wherever they occur in the hierarchy. Population likewise happens once; later `MakeAvailable` calls reuse the result. This is what lets a top-level project pin a version that a nested dependency also asks for, provided the top level declares everything **before** it calls `MakeAvailable` for anything. ## Letting an installed copy win Since CMake 3.24 a declaration can integrate with `find_package` in either direction: | Option | Effect | |---|---| | `FIND_PACKAGE_ARGS <args>...` | `MakeAvailable` first calls `find_package(<name> <args>...)`; it downloads only when that call fails | | `OVERRIDE_FIND_PACKAGE` | later `find_package(<name>)` calls are redirected to the fetched content | The user controls the first behaviour with `FETCHCONTENT_TRY_FIND_PACKAGE_MODE`, read when `FetchContent_Declare` runs: - `OPT_IN` (also the behaviour when the variable is unset): call `find_package` only for declarations that gave `FIND_PACKAGE_ARGS`; - `ALWAYS`: try `find_package` for every declaration; - `NEVER`: never call it, even when `FIND_PACKAGE_ARGS` was given. With `FIND_PACKAGE_ARGS 2.0 CONFIG` and an installed `hdr` 2.3 on `CMAKE_PREFIX_PATH`, configure reports `hdr_FOUND=1`, `hdr_DIR` points at the installed package, and nothing is downloaded. Without the installed copy, the source is fetched instead, and, because the declaration opted into `find_package` integration, FetchContent writes small `hdr-config.cmake` and `hdr-config-version.cmake` files into `CMAKE_FIND_PACKAGE_REDIRECTS_DIR`, so a later `find_package(hdr)` anywhere in the build resolves to the fetched copy. The generated version file declares every requested version compatible, because CMake cannot know an arbitrary dependency's version. ## Controls for developers and CI These cache variables change how population behaves without editing the project: - `FETCHCONTENT_SOURCE_DIR_HDR` points the `hdr` dependency at a local checkout; nothing is downloaded and `find_package` is not attempted for it, which is how a developer edits a dependency alongside the project. - `FETCHCONTENT_UPDATES_DISCONNECTED` (`OFF` by default) stops the update step contacting git or hg remotes, while a first download still happens. - `FETCHCONTENT_FULLY_DISCONNECTED` (`OFF` by default) skips download and update entirely, and is meant only for runs after the first; with policy `CMP0170` (3.30) set to `NEW`, a dependency whose source directory does not exist yet is a fatal error. - `FETCHCONTENT_TRY_FIND_PACKAGE_MODE` decides, as described above, whether installed packages are tried first. ## Release notes that change what you write - `SYSTEM` (3.25) marks the dependency's targets as system targets, so consumers see their include directories as system include directories and their warnings stay quiet. - `EXCLUDE_FROM_ALL` (3.28) keeps its targets out of the default `all` build unless something links them. - Calling `FetchContent_Populate(<name>)` with just a declared name is deprecated by policy `CMP0169` (3.30); use `MakeAvailable`. - Policy `CMP0168` (3.30) performs the download directly in the configure step instead of through a sub-build. - Pin `GIT_TAG` to a commit hash, or give `URL_HASH`, so the content is reproducible and verified. ## FetchContent versus ExternalProject `ExternalProject_Add` creates a custom target that downloads, configures, builds and installs a **separate** project during the **build** step. Nothing it produces exists while your `CMakeLists.txt` runs, so you cannot `target_link_libraries` against its targets; you must describe its outputs by hand or use a two-stage superbuild. FetchContent populates at configure time and adds the source to the same build, which is why it suits libraries you want to link directly, while ExternalProject suits tools or projects that must stay isolated, such as one with an incompatible build system.
- Two nested projects both declare the same dependency with different tags. Which tag is used?The tag from whichever `FetchContent_Declare` ran first; later declarations of that name are ignored. A top-level project that declares all its dependencies before calling `FetchContent_MakeAvailable` therefore controls the versions its subprojects receive.
- Why can't you link a target produced by ExternalProject_Add the way you link a FetchContent target?`ExternalProject_Add` builds the external project during the build step, in its own build tree, so no target for its library exists while CMake configures your project. You must describe its outputs yourself, for example with an imported target, or use a superbuild. FetchContent adds the source with `add_subdirectory` at configure time, so its targets are real targets of your build.
- FetchContent_Declare downloads the source immediately
- The last FetchContent_Declare for a name overrides earlier ones
- FetchContent downloads at build time, like ExternalProject_Add
- FIND_PACKAGE_ARGS makes find_package mandatory, failing if nothing is installed
- FETCHCONTENT_FULLY_DISCONNECTED is the right switch for a first offline configure
Assumes CMake 4.x; FIND_PACKAGE_ARGS and OVERRIDE_FIND_PACKAGE need 3.24, EXCLUDE_FROM_ALL 3.28, and single-name FetchContent_Populate is deprecated since 3.30.