Using vcpkg with CMake on Windows

4 minute read

Introduction

If you do any sort of C++ development on Windows, then you know that library/package management can be quite a pain at times (ever built OpenCV from source? How about boost?). On Windows there is no equivalent of apt-get or pacman or even homebrew; but now there is vcpkg!

vcpkg is a C++ library manager that is built by Microsoft and is open source. In fact Microsoft has pushed themselves to the forefront of open source software and vcpkg is arguably a big part of that.

Using vcpkg

Follow the instructions in the README of the vcpkg Github repo to get started. After the bootstrap process is complete, you can now install packages. These packages will be downloaded and built automatically using your local build tools. You can specify what version of Visual Studio you want vcpkg to use to build the packages.

Installing a Package

  • Open a terminal window
  • To search for a package use the following command: vcpkg search <package name>
  • Once you find the exact package name you want installed, install it with: vcpkg install <package name>.

:exclamation: Note that the <package name> name must match verbatim what vcpkg lists as the package name

Triplets

One thing to be aware of when installing packages is that vcpkg uses what are called triplets. Each triplet defines how you want to build the package you are installing. On Windows for example, the default triplet builds x86 targets (x86-windows). This may be undesireable (you may want x64 builds only). One way to change this behavior is to set the VCPKG_DEFAULT_TRIPLET environment variable to the triplet value you would like to use by default. Otherwise, you can specify the target triplet when you issue the command to vcpkg to install a package.

To use a specific triplet, you simply append the triplet to your install command. Below are two examples:

vcpkg install <package name>:x64-windows

or

vcpkg install <package name> --triplet x64-windows

To see the available triplets, go to the base vcpkg directory and open the folder named triplets. In there you’ll find a number of .cmake files that specify different build types. If you open one up, you can see the names of the variables that vcpkg uses. One of interest is VCPKG_TARGET_ARCHITECTURE. If you wnat to change your default build architecture, this is the variable name you want to use in your environment variables.

Custom Triplet

To understand how to make a custom triplet, let’s first look at one that ships with vcpkg. Open the x64-windows.cmake triplet. It’s contents should look like the following:

set(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE dynamic)

By default, CRT linkage is dynamic (i.e. via *.dll files for MSVC) and so is the library linkage. To build static libs you would use the x64-windows-static triplet which will change the linkage to static. The cool thing about vcpkg is that you can create your own custom triplets. Let’s say you wanted to use Visual Studio 2013 instead of 2017. You could make a new cmake file called x64-vs2013-dynamic.cmake and put the following into it:

set(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE dynamic)
set(VCPKG_PLATFORM_TOOLSET v120)

If you have Visual Studio 2013 properly installed on your machine, you can now install packages with vcpkg using Visual Studio 2013. To do so you just install packages as before, but use your custom triplet instead:

vcpkg install <package name>:x64-vs2013-dynamic

Using Packages Installed with vcpkg

One thing I struggled with is how to use vcpkg installs in my own projects. vcpkg thankfully integrates seamlessly with CMake. To use vcpkg all you have to do is pass the vcpkg.cmake buildsystem file as CMAKE_TOOLCHAIN_FILE variable when configuring with CMake. This CMake file is found under the scripts/buildsystems folder of your vcpkg root directory.

Full command would be something like this:

cmake -S <source> -B build "-DCMAKE_TOOLCHAIN_FILE=<path to toolchain file>"

If you use the CMake GUI, then you can still specify the toolchain file during the CMake configuration step when run for the first time.

Steps:

  • Open the CMake GUI and select your source and build directories.
  • Click Configure. When you do, you should get a window like the one below:

cmake-gui-create-build-dir

  • Click yes and then you’ll be prompted with the following window:

cmake-gui-select-generator

  • In the radio button options under the generator selector, select Specify toolchain file for cross-compiling
  • Click Next

  • In the subsequent screen, specify the full path to the toolchain file (i.e. the same vcpkg.cmake file specified above).

cmake-gui-specify-toolchain

And that’s it! Now you can use find_package() in cmake like you normally would, but now the installed package locations from vcpkg will also be searched and packages that you have installed should be found automatically.

Conclusion

I hope this short article helped you get started quickly with using vcpkg and hopefully you learned something! I definitely recommend using vcpkg since it has the potential to standardize your package management for larger projects that have a lot of dependencies. Feel free to check out my other blog posts and follow so you don’t miss one!

Hey there! Thanks for reading this article and visiting my site. Be sure to join the Discord and follow me on Github to ensure you don’t miss out on future content! Feel free to also check out my YouTube channel where I post tutorials and fun programming videos.

Leave a Comment

Your email address will not be published. Required fields are marked *

Loading...