Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 171 ยท Getting Started

Dependencies with vcpkg and Conan

Learn how C++ package managers work. Use vcpkg manifests and Conan recipes with CMake, pin versions, understand triplets and profiles, and see how dependency resolution works.

Sooner or later every C++ program wants a library you did not write: a JSON parser, a logging library, a unit-test framework, a compression library. In many languages you would type one command and be done. C++ never had a package manager in the standard, so for decades the answer was "download the source, copy it into your project, and hope". That works for a single header file. It falls apart when the library has its own dependencies, needs a specific compiler setting, or has to be built for Windows, Linux and macOS.

Two tools solve this problem today: vcpkg (from Microsoft) and Conan (from JFrog). Both download a library, build it with settings that match your project, and hand it to your build system. This lesson explains the problem they solve, shows a complete project for each, and teaches the ideas they share: versions, triplets or profiles, and dependency resolution. Our online editor compiles a single file, so the project files here are read-only. The two runnable examples show the logic that package managers are made of. If you have not met CMake yet, read Build Systems: Make and CMake first; it also gives a shorter overview of the same tools.

Why C++ dependencies are hard

A compiled C++ library is not just "code". The binary depends on the compiler, its version, the standard library, the target operating system, whether you build in debug or release mode, and even compiler flags such as -std=c++23. Two builds of the same library from the same source can be incompatible. A package manager therefore has to track the source version and the build settings.

flowchart LR
    A["Your project<br/>(manifest)"] --> B["Package manager"]
    B --> C["Resolve versions<br/>and sub-dependencies"]
    C --> D["Download sources<br/>or binary cache"]
    D --> E["Build with matching<br/>compiler settings"]
    E --> F["CMake finds the library<br/>find_package + target_link_libraries"]

What a package manager does between "I need fmt" and a working link line.

You still write #include <fmt/core.h> and call target_link_libraries in CMake. The package manager's job ends once the library is installed in a place where CMake can find it. Headers and the linker follow the same rules explained in Header Files and Multiple Source Files.

The two approaches at a glance

Question vcpkg Conan
Who runs it Microsoft, open source JFrog, open source
Where the dependency list lives vcpkg.json (a JSON manifest) conanfile.txt or conanfile.py
Package source A Git repository of "ports" (build recipes) A central index (ConanCenter) plus private servers
Build settings A triplet, such as x64-linux or x64-windows-static A profile with settings such as compiler, version, build_type
Version pinning A builtin-baseline commit plus overrides Version ranges and lockfiles
CMake integration A toolchain file A generated toolchain file and config files
Best at Simple setup, a curated catalog that builds together Fine control, binary packages, hosting your own packages

Neither tool is "the right one". Pick the one your team or your target platform already uses. The concepts transfer.

vcpkg: a manifest next to your code

vcpkg works in manifest mode: you write a file named vcpkg.json at the root of the project, and vcpkg installs exactly what it lists into your build folder.

JSON
{
  "name": "weather-report",
  "version": "0.1.0",
  "dependencies": [
    "fmt",
    "nlohmann-json",
    { "name": "catch2", "host": true }
  ],
  "builtin-baseline": "0123456789abcdef0123456789abcdef01234567"
}

The builtin-baseline is a commit of the vcpkg catalog. It freezes every package to the version that commit lists, so a teammate building next year gets the same libraries you did. Without it, versions float. The sample hash above is a placeholder; you create the real one with vcpkg x-update-baseline --add-initial-baseline. Marking catch2 as host means it is only needed on the machine that runs the build, which matters when cross-compiling.

Your CMakeLists.txt then asks for the libraries by name:

CMAKE
cmake_minimum_required(VERSION 3.25)
project(weather_report CXX)

set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(fmt CONFIG REQUIRED)
find_package(nlohmann_json CONFIG REQUIRED)

add_executable(report src/main.cpp)
target_link_libraries(report PRIVATE fmt::fmt nlohmann_json::nlohmann_json)

You point CMake at vcpkg by passing its toolchain file when you configure the project:

Terminal
git clone https://github.com/microsoft/vcpkg.git
./vcpkg/bootstrap-vcpkg.sh

cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE=./vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build

During the configure step vcpkg reads vcpkg.json, builds fmt and nlohmann-json, and puts them where find_package looks. Run it again later and nothing is rebuilt, because the results are cached.

Triplets

A triplet names the target: CPU, operating system and link style. Common ones are x64-linux, arm64-osx, x64-windows (DLLs) and x64-windows-static (everything linked into the executable). You select one with -DVCPKG_TARGET_TRIPLET=x64-windows-static. The triplet is vcpkg's version of "build settings"; change it and every dependency is rebuilt for the new target.

Pinning with overrides

The baseline fixes a whole catalog. To pin a single library to an exact version, add an overrides entry:

JSON
{
  "dependencies": [ "fmt" ],
  "builtin-baseline": "0123456789abcdef0123456789abcdef01234567",
  "overrides": [
    { "name": "fmt", "version": "10.2.1" }
  ]
}

Use overrides sparingly. Each one is a promise that you will test that combination yourself.

Conan: recipes, profiles and generators

Conan describes dependencies in a recipe. The simplest recipe is a text file called conanfile.txt:

INI
[requires]
fmt/10.2.1
nlohmann_json/3.11.3

[tool_requires]
cmake/[>=3.25]

[generators]
CMakeDeps
CMakeToolchain

[layout]
cmake_layout

[requires] lists libraries with exact versions. [tool_requires] lists programs needed to build (here, a minimum CMake version expressed as a version range). The two generators write files that CMake understands, and cmake_layout chooses sensible folder names.

You install the dependencies, then configure CMake using the toolchain Conan generated:

Terminal
conan profile detect --force
conan install . --output-folder=build --build=missing

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

The same find_package(fmt CONFIG REQUIRED) and target_link_libraries(... fmt::fmt) lines from the vcpkg example work unchanged, because both tools provide standard CMake config files. That is the main reason to prefer find_package over hard-coded include and library paths.

Profiles

A Conan profile is a file with your build settings. conan profile detect writes one for the compiler it finds:

INI
[settings]
os=Linux
arch=x86_64
compiler=gcc
compiler.version=15
compiler.libcxx=libstdc++11
compiler.cppstd=23
build_type=Release

Conan computes a package ID from these settings. If a matching prebuilt binary exists on the server, it downloads it. If not, --build=missing builds it locally. Switch to build_type=Debug and you get a different binary, as you should.

For bigger projects, write a conanfile.py instead of the text file. It is Python code, so you can add options, conditional dependencies and your own packaging steps.

Versions and what the numbers mean

Both tools rely on semantic versioning: MAJOR.MINOR.PATCH. By convention:

  • A patch release (10.2.0 to 10.2.1) fixes bugs and keeps everything compatible.
  • A minor release (10.2.1 to 10.3.0) adds features and stays compatible.
  • A major release (10.x to 11.0) may break your code.

A range such as [>=3.25] or ~10.2 (any 10.2.x) lets the tool choose, within bounds. The first runnable example below parses versions and checks a "compatible with" rule. The code is plain C++, so you can see there is no magic.

C++ Semantic versions and compatibility ranges

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

Notice the last line: 10.10.0 is newer than 10.9.0. Comparing version strings as text would get this wrong ("10.10.0" < "10.9.0" alphabetically), which is why tools parse the numbers. The defaulted operator<=> compares the three fields in order, exactly the rule you need. If the spaceship operator is new to you, see Operator Overloading.

Dependency resolution

Your project asks for library A. A needs B and C. C also needs B. The package manager has to build B before C, and C before A, and build B only once. That is a topological sort of the dependency graph.

flowchart TD
    app["weather-report"] --> fmt
    app --> json["nlohmann-json"]
    app --> http["http-client"]
    http --> ssl["openssl"]
    http --> zlib
    ssl --> zlib

A small dependency graph. zlib is shared, so it is built first and only once.

Real resolvers also handle version conflicts (A wants zlib >= 1.2, C wants zlib < 1.3) and must detect cycles. The second example runs a simplified version: it computes a valid build order and reports a cycle if one exists.

C++ Computing a build order

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

zlib appears once, before both openssl and http-client, even though two packages need it. A cycle has no valid order, so a package manager reports an error instead of looping forever. The same idea orders compile steps inside CMake, and the recursion pattern is covered in Recursion.

Practical advice

  • Commit the manifest, not the installed libraries. vcpkg.json or conanfile.txt belongs in version control. The build folder does not.
  • Pin versions. A baseline (vcpkg) or a lockfile (conan lock create) makes builds repeatable across machines and across months.
  • Match settings across the whole tree. A dependency compiled with a different C++ standard library or in Debug mode while your code is Release can crash at runtime or fail to link. Let one profile or triplet drive everything.
  • Prefer find_package and imported targets like fmt::fmt. They carry include paths, compile definitions and transitive libraries with them.
  • Check licences. A package manager makes it easy to add a dependency, but you still have to be allowed to ship it.
  • Header-only is not "free". A single-header library has no link step, but it can slow every compile that includes it. See Compiler Flags and Optimization for measuring build time.
  • Keep dependencies few. Every library is code you must update when a security fix arrives.

If you only need one small header-only library and a quick experiment, copying the file into third_party/ is fine. Switch to a package manager when you have more than a couple of libraries or more than one developer.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does vcpkg's builtin-baseline in vcpkg.json do?

    The baseline is a commit of the vcpkg port catalog. Pinning it makes builds on different machines and at different times pick the same versions.
  2. 2. In Conan, which file holds settings such as compiler, compiler.version and build_type?

    A profile describes the build settings. Conan uses them to compute a package ID and to decide whether a prebuilt binary matches.
  3. 3. Why do both tools generate CMake config files and a toolchain file?

    With config files and a toolchain, CMake finds each library and gets its include paths and link libraries from the imported target.
  4. 4. Library A needs B and C, and C also needs B. What must the resolver guarantee?

    Dependencies are built before the packages that need them, and a shared dependency is built only once. That is a topological order of the graph.

Summary

  • C++ has no standard package manager; vcpkg and Conan are the two most widely used tools.
  • vcpkg uses a vcpkg.json manifest, a baseline for reproducible versions and triplets for the target; Conan uses conanfile.txt or conanfile.py, profiles and lockfiles.
  • Both integrate with CMake through a toolchain file, so your project uses find_package and imported targets.
  • Build settings are part of a library's identity: compiler, standard library, debug or release, and link style must match.
  • Semantic versioning (MAJOR.MINOR.PATCH) tells you what an upgrade may break; parse versions as numbers, never as text.
  • Resolution is a topological sort of the dependency graph, with shared packages built once and cycles rejected.

Next: Variables, where you start storing and using data in your own programs.