Using Conan with CMake

Let's integrate Conan into our Greeter project to manage the spdlog dependency. The process involves four steps: creating the Conan manifest, installing the dependencies, updating our CMakeLists.txt, and finally configuring our project.

Step 1: Create the Conan Manifest

In the root directory of the Greeter project, create a file named conanfile.txt. This file serves the same purpose as vcpkg.json.

1[requires]
2spdlog/1.15.3
3
4[generators]
5CMakeDeps
6CMakeToolchain

The [requires] section lists all the direct dependencies your project needs. We're asking for version 1.15.3 of spdlog.

The [generators] section tells Conan which integration files to create for CMake.

• CMakeDeps: This generator creates the necessary find_package configuration files (spdlog-config.cmake, etc.) for each dependency.
• CMakeToolchain: This generator creates a single conan_toolchain.cmake file that configures CMake with all the settings from our active Conan profile (compiler, build type, etc.).

Step 2: Install the Dependencies

Now, let's install our dependencies. We first ensure we're back in our /build directory. We may also want to clean out everything in that directory, to ensure we're configuring from scratch.

Remember, we can navigate our terminal to a directory using the cd command:

1cd /path/to/project-root/build

From that location, we run conan install. This command reads a conanfile.txt, fetches the packages (ideally as pre-compiled binaries), and generates the CMake files in a specified output folder.

We need to provide three arguments:

• The location of our conanfile.txt. If we're in the /build directory, and our conanfile.txt is in the project root, we'd pass .. to refer to the parent directory.
• --output-folder specifies where to place generated files. We can put them in the current directory, /build, by passing .
• --build=missing tells Conan to build from source if a binary is not found

Our command is as follows:

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

If we wanted to use a non-default profile, we'd additionally pass its name as a --profile or --pr argument here.

After this command completes, our /build directory will contain a load of new files. The most important one is the conan_toolchain.cmake file, which we'll use soon.

Step 3: Update CMakeLists.txt

Similar to vcpkg, Conan's integration doesn't require any changes or additions to our CMakeLists.txt files. They don't need to know anything about Conan; they just call find_package() call and the conan_toolchain.cmake file (which we'll use in the next step) ensures that the package can be found:

1cmake_minimum_required(VERSION 3.16)
2
3add_executable(GreeterApp src/main.cpp)
4
5# This call is intercepted by the Conan toolchain
6find_package(spdlog CONFIG REQUIRED)
7
8target_link_libraries(GreeterApp
9  PRIVATE
10  GreeterLib
11  spdlog::spdlog
12)

A simple test app that uses our Conan-provided dependency might look something like this:

1#include <greeter/Greeter.h>
2#include <spdlog/spdlog.h> 
3
4int main() {
5  spdlog::info(get_greeting()); 
6  return 0;
7}

Step 4: Configure the CMake Project

Finally, we configure our project from the build directory. We should set the CMAKE_TOOLCHAIN_FILE to the toolchain file that Conan just generated for us, and we should provide the CMAKE_BUILD_TYPE. The build type should match the build_type value in the Conan profile we're using:

1cmake .. \
2  -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake \
3  -DCMAKE_BUILD_TYPE="Debug"

This command tells CMake to use Conan's configuration. The conan_toolchain.cmake file will, in turn, teach find_package() how to locate the libraries that Conan installed.

If everything has been configured correctly, we can build and run our project as usual.

1cmake --build .

1./app/GreeterApp

1[2025-08-20 16:18:41.740] [info] Hello from the modular greeter library!

We've solved the speed issue, but what about reproducibility? Just like with vcpkg, we need a way to ensure that every developer on the team gets the exact same version of every dependency, every time.

We saw vcpkg's primary mechanism for this was a baseline. Most other dependency managers, including Conan, solve this using a lockfile. A lockfile is text file stored and shared alongside the project that lists the entire dependency graph, capturing the exact version and revision of every direct and transitive dependency.

In Conan's case, this file is called conan.lock. The process of creating and using it looks like this:

1. Generate the Lockfile: A developer generates the lockfile using a conan command.
2. Share the Lockfile: The conan.lock file is shared alongside your project. For example, it would be committed to your version control repository.
3. Use the Lockfile: Everyone else on the team uses this committed lockfile during their conan install step.

Let's walk through these steps. First, we generate the lockfile using the conan lock create command, passing the location of our conanfile.txt. If we're in the /build directory and the conanfile.txt is in the project root, we'd pass ..:

1conan lock create ..

This creates a conan.lock file in the same location as the conanfile.txt. It might look something like this:

1{
2  "version": "0.5",
3  "requires": [
4    "spdlog/1.15.3#3ca0e9e6b83af4d0151e26541d140c86%1748617970.519",
5    "fmt/11.2.0#579bb2cdf4a7607621beea4eb4651e0f%1746298708.362"
6  ],
7  "build_requires": [],
8  "python_requires": [],
9  "config_requires": []
10}

You can see this file has recorded the version used for our direct dependency spdlog, as well as for the indirect fmt dependency that spdlog uses internally. It also tracks a revision hash and timestamp of each version, for even more assurance that we're getting the exact package we intended.

You should share this lockfile as part of your project, and then everyone else can use it for installation when doing a conan install. By default, Conan will find and use a conan.lock file that is in the same location as our conanfile.txt, so we just install things as we did before:

1conan install .. --output-folder=.

Behind the scenes, Conan will find and respect the conan.lock file:

1Using lockfile: 'D:/Projects/cmake/conan.lock'
2...
3Install finished successfully

Now, every single build, on every machine, will use an identical set of dependencies. We can explicitly provide a lockfile to the install command using the --lockfile argument:

1conan install .. \
2  --lockfile="../some-other-lockfile.lock" \
3  --output-folder=.

To prevent a lockfile being used, even if one is found next to our conanfile.txt, we'd pass an empty string:

1conan install .. --lockfile="" --output-folder=.

When we add dependencies to our project, or update the version of existing dependencies, our conan.lock file will fall out of date. For example, let's imagine we want to introduce the tabulate library:

1[requires]
2spdlog/1.15.3
3tabulate/1.4
4
5[generators]
6CMakeDeps
7CMakeToolchain

If we try a conan install now, we'll get an error:

1conan install .. --output-folder=.

1Using lockfile: 'D:/Projects/cmake/conan.lock'
2...
3ERROR: Requirement 'tabulate/1.4' not in lockfile 'requires'

Beyond creating new lockfiles, the conan lock command has several other utilities that are helpful for managing and updating lockfiles. You can read more about them on the official documentation.

However, one of the more common way of updating lockfiles is through passing arguments like --lock-partial and --lockfile-out arguments as part of a conan install command. The following command both installs our dependencies, and updates our conan.lock file:

1conan install .. \
2  --output-folder=. \
3  --lockfile-partial \
4  --lockfile-out="../conan.lock"

The --lockfile-partial argument instructs Conan to use the lockfile versions for libraries that are referenced in the lockfile - spdlog and fmt, in our case. However, for anything not in the lockfile - tabulate, in our case - just use the normal resolution process, as if the lockfile didn't exist.

The --lockfile-out argument instructs Conan to write or update the lockfile, using the versions of everything it just installed. We should now see our new tabulate/1.4 requirement tracked in our lockfile:

1{
2  "version": "0.5",
3  "requires": [
4    "tabulate/1.4#c6ab7bb7413f268432d2684a1a27bbc1%1681259966.699",
5    "spdlog/1.15.3#3ca0e9e6b83af4d0151e26541d140c86%1748617970.519",
6    "fmt/11.2.0#579bb2cdf4a7607621beea4eb4651e0f%1746298708.362"
7  ],
8  "build_requires": [],
9  "python_requires": [],
10  "config_requires": []
11}

If we want to upgrade one of our dependencies to a new version, we can update our conanfile.txt in the usual way:

1[requires]
2spdlog/1.15.3
3tabulate/1.4
4tabulate/1.5
5
6[generators]
7CMakeDeps
8CMakeToolchain

If we rerun our previous conan install command with the same arguments, our new dependency (tabulate/1.5) will be tracked, but tabulate/1.4 will still be lurking in our lockfile:

1conan install .. \
2  --output-folder=. \
3  --lockfile-partial \
4  --lockfile-out="../conan.lock"

1{
2  "version": "0.5",
3  "requires": [
4    "tabulate/1.5#7e35e527405fa23bdb97323cc0e61e24%1681259966.66",
5    "tabulate/1.4#c6ab7bb7413f268432d2684a1a27bbc1%1681259966.699",
6    "spdlog/1.15.3#3ca0e9e6b83af4d0151e26541d140c86%1748617970.519",
7    "fmt/11.2.0#579bb2cdf4a7607621beea4eb4651e0f%1746298708.362"
8  ],
9  "build_requires": [],
10  "python_requires": [],
11  "config_requires": []
12}

This is mostly harmless, but we can add the --lockfile-clean argument to our conan install command to also remove any unused dependencies from our lockfile:

1conan install .. \
2  --output-folder=. \
3  --lockfile-partial \
4  --lockfile-out="../conan.lock" \
5  --lockfile-clean

1{
2  "version": "0.5",
3  "requires": [
4    "tabulate/1.5#7e35e527405fa23bdb97323cc0e61e24%1681259966.66",
5    "spdlog/1.15.3#3ca0e9e6b83af4d0151e26541d140c86%1748617970.519",
6    "fmt/11.2.0#579bb2cdf4a7607621beea4eb4651e0f%1746298708.362"
7  ],
8  "build_requires": [],
9  "python_requires": [],
10  "config_requires": []
11}

We can clean a lockfile independently of an installation using the conan lock create command, passing the location of our conan.lock file and the --lockfile-clean argument:

1conan lock create .. --lockfile-clean

Conan offers a fast and flexible alternative for dependency management. While it requires a bit more initial setup than vcpkg, its focus on pre-compiled binaries can dramatically accelerate compilation times for complex projects.

• Binary-First Philosophy: Conan's main advantage is speed. It avoids compiling dependencies from source by downloading pre-compiled binaries that match your configuration.
• Profiles Define Environments: Conan uses profile files to understand your build environment (OS, compiler, etc.), which is the key to finding the correct binaries.
• Clean CMake Integration: The CMakeDeps and CMakeToolchain generators allow for a clean integration where your CMakeLists.txt only needs a standard find_package() call.
• Reproducibility Through Lockfiles: Generating and sharing a conan.lock file is the standard way to help with reproducible builds.