For a C++ team's CMake build, how do you choose between FetchContent and find_package fed by a package manager for third-party dependencies?
answer
- who builds the binaries
- configure time and CI cost
- one ABI across the graph
- find_package as the stable seam
- dependency providers and top-level includes
basics
~20 sWrite find_package calls as the project's single interface, and let the environment decide how they are satisfied: a package manager or prebuilt prefix for heavy or shared dependencies, FetchContent with FIND_PACKAGE_ARGS as a fallback for small, header-only or tightly pinned ones.
solid answer
~50 sThere is no single answer; the trade-offs are build cost, reproducibility, ABI consistency and who owns the binaries. FetchContent is self-contained and pins source in the repository, but rebuilds every dependency from source in every fresh build directory, needs network or a mirror at configure time, and puts the dependency's targets and options inside your build. A package manager such as Conan or vcpkg, or an internal install prefix, delivers prebuilt binaries as config packages, so configure stays fast and many projects share one consistent set, at the cost of tooling and a binary cache to run. The durable decision is the seam: every `CMakeLists.txt` uses `find_package(Name CONFIG REQUIRED)` and imported targets, `FetchContent_Declare(... FIND_PACKAGE_ARGS)` provides a fallback, and a dependency provider set through `CMAKE_PROJECT_TOP_LEVEL_INCLUDES`, or a toolchain file, plugs a package manager in without editing the project.
go deeper
Know that dependencies can arrive prebuilt through find_package or as source through FetchContent, and that both end in a target you link.
Explain configure-time source builds versus prebuilt config packages, and how FIND_PACKAGE_ARGS lets one declaration work both ways.
Spot duplicate copies, configure-time network access in CI and unpinned content, and fix them with top-level declarations, hashes and providers.
Choose per class of dependency on build cost, ABI consistency, offline needs and ownership, and keep find_package plus targets as the seam so the policy can change without project edits.
## The decision a lead owns Every non-trivial C++ project consumes third-party code: compression, formatting, a test framework, perhaps a large framework or engine. CMake offers two primary ways in, and they put the cost in different places: - **`find_package`** consumes something **already built and installed** somewhere, by system packages, by a package manager such as Conan or vcpkg, or by an internal pipeline that publishes install prefixes. - **`FetchContent`** downloads **source** during configure and builds it **as part of your build**. Choosing is a judgment call about the team, the dependency and the delivery pipeline, and it usually differs per dependency. ## The trade-offs | Concern | FetchContent from source | find_package on prebuilt packages | |---|---|---| | First configure and build time | grows with every dependency, in every new build directory | fast once binaries exist | | Reproducibility | pinned by `GIT_TAG` commit or `URL_HASH` in the repository | pinned by the package manager's lockfile or baseline | | ABI and flag consistency | built with your exact compiler and flags | must match your settings, or binaries are rebuilt | | Offline and air-gapped CI | needs a mirror or `FETCHCONTENT_SOURCE_DIR_<NAME>` | needs a binary cache or internal remote | | Dependency's own options and warnings | live inside your build (use `SYSTEM`, `EXCLUDE_FROM_ALL`) | isolated in its own build | | Sharing across many repositories | each repository rebuilds | one built set serves all | | Extra tooling to run | none beyond CMake | the package manager and its cache | ## A strategy that survives change The most reversible choice is to keep **one seam** in the project and move the policy outside it: 1. **Consume through targets only.** Every `CMakeLists.txt` links names such as `fmt::fmt` or `ZLIB::ZLIB`, never raw paths, so the provider of a target can change without touching consumers. 2. **Discover through `find_package`.** Write `find_package(Name CONFIG REQUIRED)` (or the basic signature for system libraries that need a Find module) for each dependency. 3. **Add a fallback where self-containment matters.** For small or header-only libraries, declare `FetchContent_Declare(name ... FIND_PACKAGE_ARGS ...)`, so `MakeAvailable` uses an installed copy when one is found and fetches a pinned source otherwise. 4. **Let the environment choose.** Since CMake 3.24 a **dependency provider**, installed by a file listed in `CMAKE_PROJECT_TOP_LEVEL_INCLUDES` and set with `cmake_language(SET_DEPENDENCY_PROVIDER ... SUPPORTED_METHODS FIND_PACKAGE FETCHCONTENT_MAKEAVAILABLE_SERIAL)`, can intercept both `find_package` and `FetchContent_MakeAvailable` calls. Package managers that integrate this way, or through a toolchain file, need no project edits. Developers can set `FETCHCONTENT_TRY_FIND_PACKAGE_MODE` to `NEVER` to force source builds, or `ALWAYS` to prefer installed copies. ## Rules of thumb by dependency - **Header-only and small libraries** (a formatting library, a JSON parser): FetchContent with a pinned hash and `FIND_PACKAGE_ARGS` is cheap and keeps the repository self-contained. - **Test-only dependencies** (GoogleTest, Catch2): either works; with FetchContent, `EXCLUDE_FROM_ALL` builds only the parts your test targets actually link. - **Large or slow-to-build dependencies** (a big framework, a physics or rendering engine, OpenSSL): prebuilt packages, because rebuilding them in every CI job and fresh build directory costs more than running a binary cache. - **Libraries other teams also link**: one package source, so every product links the same version with the same ABI-relevant flags and no two copies meet in one process. - **Platform libraries** (`Threads`, system `ZLIB` on some platforms): module mode with CMake's own Find modules. ## Failure modes to plan for - **Two copies of one library** when a FetchContent dependency also fetches its own version of something you find via a package. Declare shared dependencies first at the top level, since the first declaration wins, or route both through `find_package`. - **Configure-time network access** in locked-down CI. `FETCHCONTENT_FULLY_DISCONNECTED` is meant for runs after the first; for a first offline run, the FetchContent documentation recommends a dependency provider that populates from local content. - **Drift** when nobody owns upgrades. Whichever mechanism you choose, record versions in one place and give the bump a review path. ## What to standardise Write down which mechanism each class of dependency uses, how versions are pinned, which variables CI sets, and that new code consumes dependencies only through targets and `find_package`. That keeps the next change of package manager, or the move from fetched to prebuilt for a dependency that grew, a configuration change rather than an edit to every `CMakeLists.txt`.
- How can a package manager satisfy find_package calls without the project mentioning it?Through a dependency provider: a file passed in `CMAKE_PROJECT_TOP_LEVEL_INCLUDES` calls `cmake_language(SET_DEPENDENCY_PROVIDER ...)` during the first `project()` call, and the provider then intercepts `find_package` and, if declared, `FetchContent_MakeAvailable`. Integration through a toolchain file that sets search paths achieves a similar effect.
- When does moving a dependency from FetchContent to prebuilt packages pay off?When rebuilding it dominates configure or CI time, when several repositories must link the identical binary, or when its build options and warnings keep leaking into yours. If consumers already link its imported target and discovery goes through `find_package` with `FIND_PACKAGE_ARGS`, the switch only changes where the package comes from.
- FetchContent is always better because it needs no extra tools
- A package manager makes find_package unnecessary in CMakeLists.txt
- Mixing fetched and installed copies of one library is harmless
- FETCHCONTENT_FULLY_DISCONNECTED solves offline CI on a fresh checkout
- The choice must be the same for every dependency in the project