Recipe

Add a library your project depends on

Use when: your code needs a library from outside the project, and the build should get it by itself, whether that means building it from source or downloading a copy someone already built

Goal: the library's :: target, at a version you chose on purpose, linked into your own target, with CMakeLists.txt the same whichever tool fetched it

Taught in Conan 2 · extends Add a library your project depends on

1. 1

   The table below compares the three tools. For one library, the question is usually size, and whether a finished copy exists for your setup.

   • it's small and quick to build — FetchContent: declare it and make it available (§2's recipe), then go straight to Step 6.
   • it's big, or there are many, and building each one once on your machine is fine — vcpkg: follow §3's recipe, Steps 2 to 5, then Step 6 here.
   • there are many, on many platforms, and you'd like prebuilt binaries where they exist — Conan: carry on with Step 2.

   Why: all three end in the same :: target. They differ only in where the library comes from and when it's built.

2. 2

   Run conan --version, then conan profile detect. Open the profile it wrote and set compiler.cppstd to the standard your project uses.

   Example

   The detected profile said compiler.cppstd=gnu17, but the project sets C++23. Change it to compiler.cppstd=23, or pass -s compiler.cppstd=23 to conan install.

   Why: Conan 2 changed the files and commands, so a 1.x version won't work with anything below. The profile's settings decide which prebuilt binary Conan looks for first, so keep them honest about how you build.

3. 3

   List each package under [requires] as name/version, and the two CMake generators under [generators].

   Example

   [requires]
   nlohmann_json/3.12.0
   fmt/11.0.2
   
   [generators]
   CMakeDeps
   CMakeToolchain
   

   • you want one exact version — write it, as in fmt/11.0.2.
   • you want bug fixes automatically — write a range, such as fmt/[>=11 <12], then run conan lock create . and commit the conan.lock it writes.

   Why: CMakeDeps writes the files find_package looks for, and CMakeToolchain writes the file that tells CMake where they are. A range without a lockfile gives two people different versions a month apart.

4. 4

   Install into your build folder, and let Conan build anything that has no matching binary.

   Example

   conan install . --output-folder=build --build=missing
   

   This downloads prebuilt packages where ConanCenter has one for your profile, builds the rest, and writes build/conan_toolchain.cmake.

   Why: with Conan, unlike vcpkg, you run the package manager yourself first. Without --build=missing, a package with no matching binary stops the install instead of being built.

5. 5

   Pass conan_toolchain.cmake as the toolchain file, with the same build type as the profile.

   Example

   cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
   cmake --build build --config Release
   

   ⚡ Shortcut

   Add a [layout] section with cmake_layout to conanfile.txt. conan install then also writes a CMakeUserPresets.json, and on Linux and macOS you configure with cmake --preset conan-release.

   Why: the toolchain file points CMake at the files CMakeDeps wrote and matches CMake's settings to the profile.

6. 6

   In CMakeLists.txt, write find_package, then link the target it creates. This step is the same for vcpkg and Conan.

   Example

   find_package(fmt REQUIRED)
   target_link_libraries(app PRIVATE fmt::fmt)
   

   • it came from vcpkg or Conan — you need the find_package line.
   • it came from FetchContent — no find_package, just link the target.

   Why: the package manager only changes how the library arrives. Because CMakeLists.txt asks for a package and a target by name, you can switch tools without touching your code.