Conan and vcpkg

C/C++ dependency management with Conan and vcpkg. Grounded against Conan 2.32.0 and vcpkg 2026.07.29.

Contract

Field	Bound contract
Trigger	The task adds a third-party C/C++ library, writes conanfile.txt/conanfile.py or vcpkg.json, integrates a package manager with CMake, manages binary compatibility, or picks between Conan and vcpkg.
Authority	Reversible local: writes only conanfile.*, vcpkg.json, profiles, triplets, overlay ports, and the local package caches; rollback is version control plus clearing the cache. No remote mutation.
Side effect	Package installs download sources or binaries into the local Conan or vcpkg cache; conan upload pushes to a remote and requires an explicit user request.
Done	The declared dependencies resolve and the project configures and builds against them, or the failing command is reported.

Inputs

• Dependency list (required): library names; versions come from ConanCenter or the vcpkg registry.
• Build system (required): CMake integration is assumed below.
• Platform constraints (optional): cross-compilation target, static vs shared linkage, MSVC vs GCC/Clang.
• Private remote (optional): an Artifactory or Conan remote URL supplied by the user.

Procedure

1. Pick the package manager. Done when: one tool is chosen with a stated reason.

Situation	Pick
MSVC-first Windows team	vcpkg: tighter MSVC and Visual Studio integration
Prebuilt binaries in CI, no source builds	Conan: binary package cache and package IDs
Cross-compilation profiles	Conan: host/build profile split
Exact version pinning per package	Conan: explicit version references
Fast setup for a small project	vcpkg manifest mode
Open-source project with broad audience	vcpkg: lower barrier for contributors

2. Set up vcpkg in manifest mode. Done when: vcpkg.json exists and CMake configures with the vcpkg toolchain file.

git clone https://github.com/microsoft/vcpkg.git
./vcpkg/bootstrap-vcpkg.sh     # Linux/macOS; .bat on Windows

{
    "name": "myapp",
    "version": "1.0.0",
    "dependencies": [
        "zlib",
        "curl",
        { "name": "openssl", "version>=": "3.0.0" },
        { "name": "boost-filesystem", "platform": "!windows" },
        { "name": "fmt", "features": ["core"] }
    ],
    "builtin-baseline": "<vcpkg commit sha>"
}

Pin builtin-baseline to a vcpkg commit so every build resolves the same package set; get it with git -C /path/to/vcpkg rev-parse HEAD and refresh it with vcpkg x-update-baseline.

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

find_package(ZLIB REQUIRED)
find_package(CURL REQUIRED)
find_package(fmt REQUIRED)
target_link_libraries(myapp PRIVATE ZLIB::ZLIB CURL::libcurl fmt::fmt)

3. Set up Conan 2 with the CMake generators. Done when: conan install produces conan_toolchain.cmake and the project configures against it.

pip install conan
conan profile detect     # writes a default profile for the local compiler
conan profile show       # inspect it

# conanfile.txt; versions are examples, check ConanCenter for current releases
[requires]
zlib/1.3
fmt/10.2.1
openssl/3.2.0

[generators]
CMakeDeps
CMakeToolchain

[options]
openssl/*:shared=False

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

find_package(ZLIB REQUIRED)
find_package(fmt REQUIRED)
find_package(OpenSSL REQUIRED)
target_link_libraries(myapp PRIVATE ZLIB::ZLIB fmt::fmt OpenSSL::SSL OpenSSL::Crypto)

4. Cross-compile with Conan profiles. The host profile describes the target; the build profile describes the machine running the build. Done when: conan install --profile:host=<target> resolves packages for the target.

# ~/.conan2/profiles/linux-arm64
[settings]
os=Linux
arch=armv8
compiler=gcc
compiler.version=12
compiler.libcxx=libstdc++11
build_type=Release

[buildenv]
CC=aarch64-linux-gnu-gcc
CXX=aarch64-linux-gnu-g++

conan install . \
    --profile:build=default \
    --profile:host=linux-arm64 \
    --output-folder=build-arm \
    --build=missing

5. Use conanfile.py when logic is needed: conditional requirements, custom generate or build steps. Done when: the recipe's requirements, generate, and build methods cover the project's conditions.

from conan import ConanFile
from conan.tools.cmake import CMakeToolchain, CMakeDeps, CMake

class MyAppConan(ConanFile):
    name = "myapp"
    version = "1.0"
    settings = "os", "compiler", "build_type", "arch"

    def requirements(self):
        self.requires("zlib/1.3")
        self.requires("fmt/10.2.1")
        if self.settings.os == "Linux":
            self.requires("openssl/3.2.0")

    def generate(self):
        CMakeToolchain(self).generate()
        CMakeDeps(self).generate()

    def build(self):
        cmake = CMake(self)
        cmake.configure()
        cmake.build()

6. Map common libraries between the two registries. Done when: each needed library has a name in the chosen registry.

Library	vcpkg name	Conan name
zlib	zlib	zlib
OpenSSL	openssl	openssl
libcurl	curl	libcurl
{fmt}	fmt	fmt
spdlog	spdlog	spdlog
Boost	boost	boost
nlohmann-json	nlohmann-json	nlohmann_json
GoogleTest	gtest	gtest
Google Benchmark	benchmark	benchmark
SQLite	sqlite3	sqlite3
protobuf	protobuf	protobuf

For baseline pinning, triplets, overlay ports, binary caches, and lockfiles see references/package-manager-patterns.md.

Failure and recovery

• Package not found: check the name against the registry (conan search or vcpkg search); names differ between the two.
• conan install --build=missing builds from source and fails: read the package build log; a missing system tool or an unsupported setting (compiler.libcxx, arch) is the usual cause.
• Binary incompatibility (link errors, ABI mismatch): rebuild the package with the project's build_type and compiler settings; Conan package IDs encode these.
• vcpkg resolves wrong versions: pin builtin-baseline; without it the registry floats.
• CMake cannot find Conan-generated files: confirm -DCMAKE_TOOLCHAIN_FILE points at the conan_toolchain.cmake under the --output-folder used at install time.
• conan upload is a remote write: run it only when the user explicitly asks to publish.

Output

A working dependency declaration (conanfile.txt/conanfile.py or vcpkg.json), the matching CMake integration, and a verified configure and build. For selection tasks, the decision table row that applies with its reason.